From 4ece56136559d5c2984617cdd4ead836eaffad1b Mon Sep 17 00:00:00 2001 From: Noah Pederson Date: Wed, 14 Oct 2026 13:10:21 -0500 Subject: [PATCH] Expose the optional appview trace endpoint Add services.provenance.appview.traceEndpoint with a null default. Set PROVENANCE_TRACE_ENDPOINT only when an endpoint is configured. Document the VictoriaTraces example and test both option states. NixOS module checks pass. Leave host configuration unchanged. --- docs/tracing.md | 9 +++++++++ nix/modules/appview.nix | 9 +++++++++ nix/tests/modules.nix | 5 +++++ 3 files changed, 23 insertions(+) diff --git a/docs/tracing.md b/docs/tracing.md index 6c5f648..9711d72 100644 --- a/docs/tracing.md +++ b/docs/tracing.md @@ -12,6 +12,15 @@ PROVENANCE_TRACE_ENDPOINT=http://127.0.0.1:10428/insert/opentelemetry/v1/traces Use the full ingest URL. Port `10429` serves the read-only proxy, not the ingest API. An empty variable disables tracing. The service name is `provenance-appview`. +In the NixOS module, set the optional endpoint: + +```nix +services.provenance.appview.traceEndpoint = + "http://127.0.0.1:10428/insert/opentelemetry/v1/traces"; +``` + +The default is `null`, which disables tracing. + Traces cover database open, migrations, index preparation, each index drop and rebuild, and replay transactions. Batch spans include state lookups, subject lookups, record writes, and commits. Each batch uses a separate trace to limit trace size during a full archive replay. diff --git a/nix/modules/appview.nix b/nix/modules/appview.nix index 2f5d4c8..daa88e2 100644 --- a/nix/modules/appview.nix +++ b/nix/modules/appview.nix @@ -32,6 +32,12 @@ in dataDirectory = common.dataOption cfg.stateDirectory; externalWorkers = common.externalWorkersOption; logLevel = common.logLevelOption; + traceEndpoint = lib.mkOption { + type = lib.types.nullOr lib.types.str; + default = null; + example = "http://127.0.0.1:10428/insert/opentelemetry/v1/traces"; + description = "Full OTLP/HTTP trace ingest URL. Null disables tracing. Do not include credentials, query parameters, or fragments."; + }; databaseFile = common.databaseOption "appview.db"; serviceKeyFile = common.secretOption "Absolute runtime path to the shared service key. Keep the file outside the Nix store."; @@ -124,6 +130,9 @@ in ENABLE_SOFT_VOUCH = lib.boolToString cfg.enableSoftVouch; ENABLE_SOFT_VOUCH_LISTS = lib.boolToString cfg.softVouchLists; ENABLE_SOFT_VOUCH_ALL_AUTHORS = lib.boolToString cfg.softVouchAllAuthors; + } + // lib.optionalAttrs (cfg.traceEndpoint != null) { + PROVENANCE_TRACE_ENDPOINT = cfg.traceEndpoint; }; }; } diff --git a/nix/tests/modules.nix b/nix/tests/modules.nix index 2ad5823..1e98361 100644 --- a/nix/tests/modules.nix +++ b/nix/tests/modules.nix @@ -99,6 +99,7 @@ let dataDirectory = "/srv/provenance/graph"; jetstreamReplay = true; jetstreamAPIKeyFile = "/run/agenix/jetstream"; + traceEndpoint = "http://127.0.0.1:10428/insert/opentelemetry/v1/traces"; }; services.provenance.ui.dataDirectory = "/srv/provenance/ui"; } @@ -122,6 +123,10 @@ let ]).services.provenance.appview.hopPenalty; in assert valid custom; +assert + custom.systemd.services.provenance-appview.environment.PROVENANCE_TRACE_ENDPOINT + == "http://127.0.0.1:10428/insert/opentelemetry/v1/traces"; +assert !(appUnit.environment ? PROVENANCE_TRACE_ENDPOINT); assert custom.systemd.services.provenance-appview.environment.PROVENANCE_APPVIEW_DB == "/srv/provenance/graph/graph.sqlite"; -- 2.54.0