{
  "schema_version": "1.3.0",
  "slug": "under-what-conditions-must-an-instance-abandon-head-based-trace-sampling-to-preserve-redaction-guarantees",
  "title": "Under what conditions must an instance abandon head-based trace sampling to preserve redaction guarantees",
  "date_of_record": "2026 November 13",
  "scope": "Applies to LLM application tracing pipelines where spans carry prompt/completion payloads and redaction is performed at the collector or exporter stage. Does not apply to pipelines where redaction is enforced at the SDK before span creation, or where sampling decisions are made after payload scrubbing.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/under-what-conditions-must-an-instance-abandon-head-based-trace-sampling-to-preserve-redaction-guarantees.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/under-what-conditions-must-an-instance-abandon-head-based-trace-sampling-to-preserve-redaction-guarantees.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/under-what-conditions-must-an-instance-abandon-head-based-trace-sampling-to-preserve-redaction-guarantees.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1131,
    "python_slice_tokens": 214,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The distinction is between **sampling as a volume-control decision** and **sampling as a confidentiality decision**. In head-based sampling, the decision to keep or drop a trace is made at the root span, before child spans exist and before their payloads are known. Redaction, by contrast, is a per-span, per-field transformation that requires access to the pa...",
    "what_was_observed": "A pipeline configured with `head_sample_rate=0.05`, a collector-side redaction processor attached to the exporter, and a 30-second tail-sampling buffer. Under nominal load, redaction coverage was reported as 100% because the exporter saw only scrubbed spans. During an incident replay, an engineer pulled the buffer contents and found **unredacted prompt text for every dropped span** — roughly 95% of traffic — because ...",
    "condition_of_validity": "Head-based sampling is safe **only** when all of the following hold: 1. Redaction runs at span creation (SDK-side) or at the first point of persistence, not at export. 2. No intermediate component (tail buffer, retry queue, dead-letter sink, sampling evaluator) persists raw span attributes. 3. The sampling decision does not alter which redaction rules apply ...",
    "decision_boundary": "Switch from head-based to redact-then-sample when **any** of the following is true: - The collector retains dropped spans in any form (buffer, queue, secondary sink). - Redaction rules depend on fields that sampling might strip (e.g., a `user_tier` attribute used to select a stricter rule set). - The sampling decision is made before the payload is materializ...",
    "operational_effect": "After migrating to redact-then-sample, prompt-redaction coverage measured at the buffer dropped from 5% to 100%, and per-span CPU cost rose ~8% on dropped spans (hashing and token replacement). The more important effect was architectural: the redaction processor moved *upstream* of the sampler, which forced the sampling policy to be expressed in terms of scr..."
  },
  "matched_failure_symptoms": [
    "SECRET_OR_PII_LEAK_IN_LOGS"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "aa3f86beaa0c64de55bd17798975ef04750c6bf3386979f2a8a661e582deb61d",
    "verified_classes": [
      "RedactionCoverageError"
    ],
    "verified_functions": [
      "assert_sampling_safe",
      "configure_sampler"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 4,
    "raised_exceptions": [
      "RedactionCoverageError"
    ],
    "sample_fail_closed_invariants": [
      "tail-sampling buffer retains raw attributes; switch to redact-then-sample before enabling head sampling"
    ],
    "stdlib_dependencies": [],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}