From 6cb072d7f917fe7302c66ebd111a1bdded7fa6dc Mon Sep 17 00:00:00 2001 From: YaroslavVlasenko Date: Thu, 6 Aug 2026 20:14:02 +0300 Subject: [PATCH 1/3] DOC: Add telemetry configuration details, including metrics, logs, traces, and associated labels and endpoints --- src/services/cloud/selfhosteddocker.md | 50 +++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/src/services/cloud/selfhosteddocker.md b/src/services/cloud/selfhosteddocker.md index 842ad6310..b9d15fbe1 100644 --- a/src/services/cloud/selfhosteddocker.md +++ b/src/services/cloud/selfhosteddocker.md @@ -41,7 +41,7 @@ image (see Updating). | `PROPERTIES` | no | Fully-qualified `aspect.property` allow-list (and default) for the per-request `values` selector. Requires the `CloudV5Bespoke` product on the license. | | `DISABLED_ELEMENTS` | no | Comma-separated list of pipeline elements to remove, e.g. `TacEngine,NativeEngine,RobotsTxtEngineBuilder`. | | `IPI_CONCURRENCY` | no | Number of concurrent handles in the @ipintelligence engine pool (an unsigned integer). Raise this when peak request rates trigger "Insufficient handles available in the pool" errors. Default = `128`. Invalid or zero values fall back to the default. | -| `REGION_NAME` | no | Free-text region label returned in the `51D-Region` response header and from `/api/info`. | +| `REGION_NAME` | no | Free-text region label returned in the `51D-Region` response header and from `/api/info`, and attached as the `region` label on exported telemetry (see Telemetry below). | | `ASPNETCORE_URLS` | no | Override the in-container listen address/port (the image listens on `8080` by default). | | `PipelineOptions__Elements__DidOnPremiseEngineBuilder__BuildParameters__IdDomain` | no | The domain embedded and cryptographically signed into every generated [51Did](@ref Identifiers_51Did). Defaults to `51d.es`. Override only if your 51Dids must be attributed to a different domain. | | `PipelineOptions__Elements__CloudJavaScriptBuilderElement__BuildParameters__Host` | no | The host the generated client-side JavaScript calls back to. Default (unset) = the host the request arrived on (the forwarded `Host` header). Override only to force callbacks to a fixed host. | @@ -96,6 +96,54 @@ curl "http://localhost:8080/api/v4/json?user-agent=Mozilla/5.0%20(iPhone)&client Interactive API documentation is served at `http://localhost:8080/api-docs`. +# Telemetry + +The container can push its own telemetry: metrics, logs and traces, each sent +over OTLP HTTP. This is off by default, and nothing ever goes to 51Degrees: +each signal is exported only when you enable the push and give that signal an +endpoint URL of your own. + +- **Metrics** - request metrics from ASP.NET Core, and .NET runtime metrics + such as CPU, memory, GC and thread pool usage. +- **Logs** - the service's log stream. +- **Traces** - a trace per handled request, with unhandled exceptions recorded + on the span. Query string values are redacted from spans by default; see the + redaction variable below. + +Every signal carries `node`, `region` and `provider` resource labels taken from +`INSTANCE_NAME`, `REGION_NAME` (see the table above) and `PROVIDER_NAME`, so +containers in a fleet can be told apart at the backend. + +| Variable | Description | +| -------- | ----------- | +| `LogServices__OpenTelemetry__Enabled` | Master switch for the OTLP push. Defaults to `false`. | +| `LogServices__OpenTelemetry__MetricsEndpoint` | OTLP HTTP ingest URL for metrics. Metrics are exported only when this is set. | +| `LogServices__OpenTelemetry__LogsEndpoint` | OTLP HTTP ingest URL for logs. Logs are exported only when this is set. | +| `LogServices__OpenTelemetry__TracesEndpoint` | OTLP HTTP ingest URL for traces. Traces are exported only when this is set. | +| `LogServices__OpenTelemetry__Headers` | Headers sent with every OTLP export, as comma separated `key=value` pairs, e.g. `Authorization=Bearer `. | +| `LogServices__OpenTelemetry__TracesSampleRatio` | Fraction of requests traced, between 0 and 1. Defaults to 1, which traces every request. | +| `OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION` | Set to `true` to keep query string values in spans, so a caller's request can be reproduced from its trace. Redacted by default. | +| `INSTANCE_NAME` | `node` label on the exported telemetry, also returned in the `51D-Instance` response header. Defaults to the machine name. | +| `PROVIDER_NAME` | `provider` label on the exported telemetry, e.g. `hetzner`. No label is attached when unset. | + +Any backend that accepts OTLP over HTTP works. This example points the three +signals at VictoriaMetrics, VictoriaLogs and VictoriaTraces: + +```{bash} +docker run -d --name 51d-cloud \ + -p 8080:8080 \ + -e LICENSE_KEYS= \ + -e LogServices__OpenTelemetry__Enabled=true \ + -e LogServices__OpenTelemetry__MetricsEndpoint=https://victoriametrics:8428/opentelemetry/v1/metrics \ + -e LogServices__OpenTelemetry__LogsEndpoint=https://victorialogs:9428/insert/opentelemetry/v1/logs \ + -e LogServices__OpenTelemetry__TracesEndpoint=https://victoriatraces:10428/insert/opentelemetry/v1/traces \ + -e "LogServices__OpenTelemetry__Headers=Authorization=Bearer " \ + -e INSTANCE_NAME=node-1 \ + -e REGION_NAME=eu \ + -e PROVIDER_NAME=hetzner \ + 51degrees/cloud-private +``` + # Updating Both the software and the data files ship inside the image, so updating either From 74807d6793d4817edc07bb8199a0e836c49925c5 Mon Sep 17 00:00:00 2001 From: YaroslavVlasenko Date: Mon, 10 Aug 2026 10:11:13 +0300 Subject: [PATCH 2/3] DOC: Expand trace span details with `pipeline.process` evidence attributes, additional redaction rules, and configuration for evidence inclusion --- src/services/cloud/selfhosteddocker.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/services/cloud/selfhosteddocker.md b/src/services/cloud/selfhosteddocker.md index b9d15fbe1..2a3401dbc 100644 --- a/src/services/cloud/selfhosteddocker.md +++ b/src/services/cloud/selfhosteddocker.md @@ -107,8 +107,14 @@ endpoint URL of your own. such as CPU, memory, GC and thread pool usage. - **Logs** - the service's log stream. - **Traces** - a trace per handled request, with unhandled exceptions recorded - on the span. Query string values are redacted from spans by default; see the - redaction variable below. + on the span. A request that reaches pipeline processing also carries a + `pipeline.process` child span with the resource key and the request evidence + (headers, query values, client hints) as attributes, plus a client span for + every outbound HTTP call the service makes. Evidence values that carry an IP + address, an email address or hashing salt, a license key, or an + `Authorization`/`Cookie` header are always exported as `[redacted]`, + whatever the variables below say. Query string values on the server span are + redacted by default; see the redaction variable below. Every signal carries `node`, `region` and `provider` resource labels taken from `INSTANCE_NAME`, `REGION_NAME` (see the table above) and `PROVIDER_NAME`, so @@ -122,6 +128,7 @@ containers in a fleet can be told apart at the backend. | `LogServices__OpenTelemetry__TracesEndpoint` | OTLP HTTP ingest URL for traces. Traces are exported only when this is set. | | `LogServices__OpenTelemetry__Headers` | Headers sent with every OTLP export, as comma separated `key=value` pairs, e.g. `Authorization=Bearer `. | | `LogServices__OpenTelemetry__TracesSampleRatio` | Fraction of requests traced, between 0 and 1. Defaults to 1, which traces every request. | +| `LogServices__OpenTelemetry__TracesIncludeEvidence` | Set to `false` to drop the request evidence attributes from `pipeline.process` spans, for installations that must not keep request data in traces. Defaults to `true`. The `[redacted]` values described above stay redacted either way. | | `OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION` | Set to `true` to keep query string values in spans, so a caller's request can be reproduced from its trace. Redacted by default. | | `INSTANCE_NAME` | `node` label on the exported telemetry, also returned in the `51D-Instance` response header. Defaults to the machine name. | | `PROVIDER_NAME` | `provider` label on the exported telemetry, e.g. `hetzner`. No label is attached when unset. | From d0d1a66e908868aa4f9ea21fba87309de66cd7b1 Mon Sep 17 00:00:00 2001 From: YaroslavVlasenko Date: Mon, 10 Aug 2026 18:13:23 +0300 Subject: [PATCH 3/3] DOC: Clarify `TracesSampleRatio` configuration and usage best practices in selfhosteddocker.md --- src/services/cloud/selfhosteddocker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/services/cloud/selfhosteddocker.md b/src/services/cloud/selfhosteddocker.md index 2a3401dbc..77732b2fd 100644 --- a/src/services/cloud/selfhosteddocker.md +++ b/src/services/cloud/selfhosteddocker.md @@ -127,7 +127,7 @@ containers in a fleet can be told apart at the backend. | `LogServices__OpenTelemetry__LogsEndpoint` | OTLP HTTP ingest URL for logs. Logs are exported only when this is set. | | `LogServices__OpenTelemetry__TracesEndpoint` | OTLP HTTP ingest URL for traces. Traces are exported only when this is set. | | `LogServices__OpenTelemetry__Headers` | Headers sent with every OTLP export, as comma separated `key=value` pairs, e.g. `Authorization=Bearer `. | -| `LogServices__OpenTelemetry__TracesSampleRatio` | Fraction of requests traced, between 0 and 1. Defaults to 1, which traces every request. | +| `LogServices__OpenTelemetry__TracesSampleRatio` | Fraction of requests traced, between 0 and 1. Defaults to 1, which traces every request; keep it well below 1 in production, since sampling happens before the outcome of a request is known and the ratio is what bounds the volume of successful-request traces. | | `LogServices__OpenTelemetry__TracesIncludeEvidence` | Set to `false` to drop the request evidence attributes from `pipeline.process` spans, for installations that must not keep request data in traces. Defaults to `true`. The `[redacted]` values described above stay redacted either way. | | `OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION` | Set to `true` to keep query string values in spans, so a caller's request can be reproduced from its trace. Redacted by default. | | `INSTANCE_NAME` | `node` label on the exported telemetry, also returned in the `51D-Instance` response header. Defaults to the machine name. |