{"record":{"id":"a8912e8eb4e57a25","repo":"denoland/deno","slug":"env-var-otel-traces-sampler-specifies-an-unsupport","errorCode":null,"errorMessage":"Env var OTEL_TRACES_SAMPLER specifies an unsupported sampler: {}","messagePattern":"Env var OTEL_TRACES_SAMPLER specifies an unsupported sampler: (.+?)","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"ext/telemetry/lib.rs","lineNumber":1175,"sourceCode":"      },\n      \"traceidratio\" => Sampler {\n        parent_based: false,\n        root: RootSampler::TraceIdRatio(ratio()),\n      },\n      \"parentbased_always_on\" => Sampler {\n        parent_based: true,\n        root: RootSampler::AlwaysOn,\n      },\n      \"parentbased_always_off\" => Sampler {\n        parent_based: true,\n        root: RootSampler::AlwaysOff,\n      },\n      \"parentbased_traceidratio\" => Sampler {\n        parent_based: true,\n        root: RootSampler::TraceIdRatio(ratio()),\n      },\n      other => {\n        return Err(deno_core::anyhow::anyhow!(\n          \"Env var OTEL_TRACES_SAMPLER specifies an unsupported sampler: {}\",\n          other\n        ));\n      }\n    };\n    Ok(sampler)\n  }\n\n  /// Returns whether a span with the given `trace_id` should be sampled\n  /// (recorded and exported), given its `parent` span context if any.\n  fn should_sample(\n    &self,\n    parent: Option<&SpanContext>,\n    trace_id: TraceId,\n  ) -> bool {\n    let parent_decision = parent.and_then(|parent| {\n      (self.parent_based && parent.is_valid()).then(|| parent.is_sampled())\n    });","sourceCodeStart":1157,"sourceCodeEnd":1193,"githubUrl":"https://github.com/denoland/deno/blob/9ad36f7a2cce60488e6ec52283efb32efddaf93a/ext/telemetry/lib.rs#L1157-L1193","documentation":"Deno's OpenTelemetry integration reads OTEL_TRACES_SAMPLER when telemetry is enabled (e.g. `deno run --otel`). The value is matched (case-sensitively, after trimming whitespace) against the six sampler names from the OTel SDK environment-variable spec: always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio. Any other string aborts telemetry initialization with this anyhow error.","triggerScenarios":"Running with --otel while OTEL_TRACES_SAMPLER is set to a non-spec value: 'AlwaysOn' (wrong case), 'parentbased_jaeger_remote' or 'traceidratiobased' (samplers other SDKs support), 'parentbased_traceidratio ' handled but 'parentbased-traceidratio' (hyphen typo) is not.","commonSituations":"Copying .env files from other OTel distributions (Jaeger remote sampler, X-Ray sampler); capitalizing the value because the OTel docs show mixed case in prose; trailing whitespace is tolerated but internal case is not; CI pipelines injecting sampler config via secrets managers that mangle values.","solutions":["Set OTEL_TRACES_SAMPLER to one of the six exact lowercase values: always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio","Unset the variable entirely (Deno then defaults to sampling every span, i.e. always_on behavior)","If you wanted probabilistic sampling, use traceidratio plus OTEL_TRACES_SAMPLER_ARG=0.25 (a number in [0,1])","Print the raw value (e.g. `env | grep OTEL_TRACES`) to spot casing/typo/invisible-character problems from copied config"],"exampleFix":"# before\nexport OTEL_TRACES_SAMPLER=ParentBased_AlwaysOn  # -> unsupported sampler\ndeno run --otel app.ts\n\n# after\nexport OTEL_TRACES_SAMPLER=parentbased_always_on\ndeno run --otel app.ts","handlingStrategy":"validation","validationCode":"// Validate before launching `deno run --otel`\nconst ALLOWED_SAMPLERS = new Set([\n  \"always_on\", \"always_off\", \"traceidratio\",\n  \"parentbased_always_on\", \"parentbased_always_off\", \"parentbased_traceidratio\",\n]);\nconst raw = Deno.env.get(\"OTEL_TRACES_SAMPLER\");\nconst v = raw?.trim();\nif (v && !ALLOWED_SAMPLERS.has(v)) {\n  throw new Error(`OTEL_TRACES_SAMPLER='${raw}' is not one of: ${[...ALLOWED_SAMPLERS].join(\", \")}`);\n}","typeGuard":null,"tryCatchPattern":"// Startup aborts the process; catch at the spawn layer\nconst cmd = new Deno.Command(\"deno\", { args: [\"run\", \"--otel\", \"app.ts\"], env });\nconst { code, stderr } = await cmd.output();\nif (code !== 0 && new TextDecoder().decode(stderr).includes(\"unsupported sampler\")) {\n  // fix env and relaunch with OTEL_TRACES_SAMPLER=parentbased_always_on\n}","preventionTips":["Keep OTel env values in one validated config module or .env file that a preflight check parses","Use exact lowercase snake_case values from the OTel SDK env-var spec","Add a CI step that greps OTEL_* vars against the allow-list before deploy"],"tags":["otel","tracing","sampler","env-var","configuration","startup"],"backgroundTag":"invalid-env-var-value","analyzedSha":"9ad36f7a2cce60488e6ec52283efb32efddaf93a","analyzedAt":"2026-08-20T13:07:44.778Z","contentChangedAt":"2026-08-20T13:07:44.778Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}