Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 2 additions & 11 deletions Darling/Darling.Tests/DarlingCollectorToggleExitCodeTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ public sealed class DarlingCollectorToggleExitCodeTests
private const int UsageOrConfig = DarlingCliCommands.CollectorToggleExitCode.UsageOrConfig;
private const int StoreUnavailable = DarlingCliCommands.CollectorToggleExitCode.StoreUnavailable;

/// <summary>Scripts compare against the numbers, so the numbers are pinned, and the README lists the same
/// three next to <c>--check-settings</c>'s.</summary>
/// <summary>Scripts compare against the numbers, so the numbers are pinned. The command line reference
/// (docs/darling/cli.md) lists the same three.</summary>
[Fact]
public void TheExitCodes_AreTheDocumentedNumbers()
{
Expand All @@ -42,19 +42,10 @@ public void TheExitCodes_AreTheDocumentedNumbers()
Assert.Equal(2, DarlingCliCommands.CollectorToggleExitCode.StoreUnavailable);

var readme = RepoFile.ReadRepoFile("Darling", "README.md");
Assert.Contains("`--enable-collector` and `--disable-collector` (described under", readme, StringComparison.Ordinal);
Assert.Contains("`0` the row was written and read back, `1` a usage or configuration problem", readme, StringComparison.Ordinal);
Assert.Contains("`2` the store could not be reached or refused the change", readme, StringComparison.Ordinal);

/* A wrong password is the store's answer, so it exits 2: the README must not say the codes separate a
script's own mistake from a store that is down. */
Assert.Contains("`2` when the store cannot be reached, refuses the login, or refuses the change", readme, StringComparison.Ordinal);
Assert.DoesNotContain("tell its own mistake from a store that is down", readme, StringComparison.Ordinal);

/* The two verbs do not file every case under the same code, and the README says which differ. */
Assert.Contains(
"a managed credential that was never stored exits `1` from the collector verbs (the setup is not finished) and `2` from `--check-settings` (there is no store to check)",
readme, StringComparison.Ordinal);
}

/// <summary>A TCP port nothing is listening on, proven closed by bind-then-release, so a connection attempt
Expand Down
5 changes: 0 additions & 5 deletions Darling/Darling.Tests/DropXeSessionsVerbTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -1328,11 +1328,6 @@ public void TheReadmeSaysWhenToRunTheNamedForm_WhatItStops_WhatToRunAfterTheRemo
var collector = readme[collectorAt..Math.Min(readme.Length, collectorAt + 500)];
Assert.Contains("If that attempt failed or ran out of time", collector, StringComparison.Ordinal);
Assert.Contains("`--drop-xe-sessions --print-sql`", collector, StringComparison.Ordinal);

// The list of verbs that survive an unusable store connection names this one.
var listAt = readme.IndexOf("Every other verb that opens the store (", StringComparison.Ordinal);
Assert.True(listAt >= 0, "the README no longer lists the verbs that open the store");
Assert.Contains("`--drop-xe-sessions <server-name>`", readme[listAt..Math.Min(readme.Length, listAt + 400)], StringComparison.Ordinal);
}

[Fact]
Expand Down
8 changes: 4 additions & 4 deletions Darling/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,11 +151,11 @@ PerformanceMonitor.Darling.Service.exe --check-settings [--json]

It prints the host facts (OS, containerization, CPUs, RAM) and the store facts (versions, size, lifetime buffer hit ratio, temp bytes, and how many bytes of uncompressed TimescaleDB chunks sit against RAM). Then it prints one row per setting: its live value, where that value came from, what this host would derive for it right now, and a verdict. The four verdicts are `matches`; `stale-after-hardware-change` (a managed block set it once, but re-deriving from the CURRENT host gives a different number — the case a RAM upgrade or an added hypertable creates, and the reason this verb exists); `operator-override` (an `ALTER SYSTEM`, or a hand-edited line after the managed blocks, is what is actually in force); and `not-managed` (a bring-your-own store, where this class never wrote a block to compare against). `--json` prints the same facts as JSON for scripting. This is diagnostic only: it never writes a setting, and the service always starts regardless of what it finds.

Exit codes separate the failure kinds so an install/upgrade script can gate on them precisely: `0` nothing is stale, `1` the config failed to load or validate, or its store setting cannot be used (a connection string that cannot be parsed, or a managed credential that cannot be read), `2` the store could not be reached (a managed credential that was never stored included: there is no store to check), `3` at least one setting is `stale-after-hardware-change`.
Exit codes: see [`--check-settings` in the command line reference](../docs/darling/cli.md#exit-codes).

`--enable-collector` and `--disable-collector` (described under "Enable or disable a collector headlessly" below) separate their failures into the same three kinds, but they do not file every case under the same code as `--check-settings`: `0` the row was written and read back, `1` a usage or configuration problem (bad arguments, a config that is missing or invalid, a connection string that cannot be used, a managed store's credential that is not stored or cannot be read, an unknown collector, or a `--server` that names no server or more than one), `2` the store could not be reached or refused the change (a refused login, and a failure reading the row back after the write went through, included). The one case that differs: a managed credential that was never stored exits `1` from the collector verbs (the setup is not finished) and `2` from `--check-settings` (there is no store to check). An empty `postgres.connectionString` is `1` from both: `--check-settings` rejects it when it validates the config.
Exit codes for `--enable-collector` and `--disable-collector`: see [the command line reference](../docs/darling/cli.md#exit-codes).

Every other verb that opens the store (`--validate-config`, `--enable-mcp`, `--disable-mcp`, `--enable-web`, `--disable-web`, `--collapse-legacy-slices`, `--recompress-plan-dim`, `--add-server`, `--backfill-rollups` and `--drop-xe-sessions <server-name>`; the `--print-sql` form connects to nothing) prints the problem and exits `1` when the connection string cannot be used or the managed credential cannot be read, instead of ending in an unhandled exception. `--backfill-rollups`, `--collapse-legacy-slices` and `--recompress-plan-dim` run on any platform against a bring-your-own store; on a non-Windows host they refuse only a managed store, whose credential only Windows can read (#6071).
Every other verb, with its exit codes, platform rules and whether it needs the service running, is in the [command line reference](../docs/darling/cli.md).

### Diagnostics Bundle

Expand All @@ -171,7 +171,7 @@ Server, host, database, login and domain names and IP addresses are replaced wit

When the store cannot be reached, the registry cannot be read, so a server known only to it cannot be aliased: the service log is then written as counts only. `--include-log-text` adds the message text anyway (open the file before you attach it). `--alias-map` refuses to overwrite the bundle or an existing file without `--force`. The `store_unreachable` section holds no sentence, only an error class and a fixed reason code. For a managed store the bundle reads the store's own `postmaster.pid` when the first connect is refused: a store listening on another port than `postgres.port` is used there (a warning says so; the service reads the port only at start-up), and a store still starting is waited for (about 20 seconds). If it still cannot connect, the reason is `store_not_running` (no live store on the data directory, so start the service and read its log), `store_starting`, or `data_directory_missing` (the bundle is reading a `darling.json` whose data directory is not the service's: pass `--config` with the install folder's file); a bare `connect_failed` means the store is listening on the configured port and still refused.

Exit codes: `0` written, `1` bad arguments or config, `2` the store could not be reached (a reduced bundle is still written), `3` written but one or more sections failed, `4` the output path cannot be used, `5` a known name or secret survived aliasing (nothing written). If the service log is not where the verb looks, the `service_log` section says so; pass `--log-dir`.
Exit codes: see [`--diagnostics-bundle` in the command line reference](../docs/darling/cli.md#exit-codes). If the service log is not where the verb looks, the `service_log` section says so. Pass `--log-dir`.

### Run It — Console Mode

Expand Down
3 changes: 2 additions & 1 deletion docs/darling/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Read these pages in this order. After the install, each page is complete on its
3. [The web dashboard](web-dashboard.md): the browser view that the service serves.
4. [Darling MCP setup](mcp.md): the endpoint for an LLM client.
5. [Running Darling day to day](admin.md): add or remove a server, change a password, rotate a token, pause, upgrade, uninstall, and where everything is.
6. [Troubleshooting](../troubleshooting.md#darling): a table of what you see, the likely cause and the fix, for Darling and Lite.
6. [Command line reference](cli.md): every verb of the service exe, with exit codes.
7. [Troubleshooting](../troubleshooting.md#darling): a table of what you see, the likely cause and the fix, for Darling and Lite.

For every config field and permission, see the [Darling operator guide](../../Darling/README.md).
Loading
Loading