diff --git a/docs/scheduler/observability.md b/docs/scheduler/observability.md index 5b8e7cf4..3bd06be8 100644 --- a/docs/scheduler/observability.md +++ b/docs/scheduler/observability.md @@ -259,16 +259,16 @@ while lines that never had one signal nothing of the sort. ### Why Explore's level buttons need the datasource told The stored field is `severity_text`, and Grafana's log-level buttons filter on -a field called `level` — a name no row here carries. That is not something the +a field called `level` — a name no row here carries. That's not something the pipeline can fix: VictoriaLogs' OTLP ingester names the stored field `severity_text` unconditionally (v1.52.0, `app/vlinsert/opentelemetry/pb.go`), and its ingest parameters have no `_level_field` sibling to rename it with. -So the datasource is told instead. `nix/host-modules/swarm-grafana.nix` +The datasource is told instead. `nix/host-modules/swarm-grafana.nix` provisions the VictoriaLogs datasource with a `logLevelRules` entry per severity in the table above, each matching `severity_text` against one of those values — which is the plugin's way of saying "the level lives in this -field". `logLevelRules` is the datasource plugin's own jsonData key and the +field." `logLevelRules` is the datasource plugin's own jsonData key and the only level-related one it has — there is no single "the level lives in field X" string to set, so mapping every level takes one rule each. A level button then filters on `level` **or** the matching `severity_text`, and the store @@ -282,14 +282,14 @@ level:contains_common_case("info","information","informational","notice") to that OR `severity_text:="INFO"`, which our rows do match. -`Unspecified` is deliberately left out of those rules. It is VictoriaLogs' own -rendering of an absent severity, and it is what the **Log rows with no +`Unspecified` is deliberately left out of those rules. It's VictoriaLogs' own +rendering of an absent severity, and it's what the **Log rows with no severity** panel counts — giving it a level would dress the missing data up as a colour and retire the instrument that measures it. #### Three ways to get a `logLevelRules` entry wrong, all of them silent -Grafana accepts any jsonData it does not recognise, so a bad rule provisions +Grafana accepts any jsonData it doesn't recognise, so a bad rule provisions cleanly and the affected level button goes on returning zero rows: - `enabled` must be literally `true`, not merely not-false. The query