Distributed Tracing

Audience

Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

Source Truth

• Public route: tracing
• Source document: helm-ai-enterprise/docs/public/tracing.md
• Public manifest: helm-ai-enterprise/docs/public-docs.manifest.json
• Source inventory: helm-ai-enterprise/docs/source-inventory.manifest.json
• Validation: corepack pnpm run docs:coverage, corepack pnpm run docs:truth, and npm run coverage:inventory from docs-platform

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Troubleshooting

HELM Kernel supports OpenTelemetry (OTEL) distributed tracing out-of-the-box. This capability allows you to visualize the full lifecycle of an AI agent's execution intent as it securely passes through the HELM architecture.

Architecture

HELM instruments the critical path using go.opentelemetry.io/otel:

1. API Gateway / Proxy: Traces incoming external tool calls.
2. Guardian (PEP): Records policy evaluations, temporal interventions, and context bounds.
3. Safe Executor: Traces the actual tool dispatch, cryptographic signature validation, and ProofGraph receipt generation.

Running Jaeger Locally

To visualize these traces locally during development, HELM includes a Jaeger all-in-one Compose file:

cd deploy/
docker-compose -f jaeger-docker-compose.yml up -d

Jaeger's UI will be available at http://localhost:16686.

Configuring the Kernel

To run the HELM server with tracing enabled, set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable. By default, it will fall back to localhost:4317 (the default Jaeger gRPC receiver port).

export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
helm server

As the HELM server processes tasks, traces are batched and exported via gRPC to the configured collector.

Integration

If you deploy HELM in a Kubernetes cluster, you can point the OTLP exporter to your OpenTelemetry Collector DaemonSet, which can route traces to Datadog, Honeycomb, New Relic, or AWS X-Ray.

Diagram

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        request["Governed request"]
        executor["Executor span"]
        collector["OTLP collector"]
        backend["Tracing backend"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        gateway["Gateway / proxy span"]
        guardian["Guardian decision span"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt span"]
    end

    %% Operational Flow Edges
    request --> gateway
    gateway --> guardian
    guardian --> executor
    executor --> receipt
    receipt --> collector
    collector --> backend

    %% Premium Styling Rules
    style gateway fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style guardian fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        request["Governed request"]
        executor["Executor span"]
        collector["OTLP collector"]
        backend["Tracing backend"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        gateway["Gateway / proxy span"]
        guardian["Guardian decision span"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt span"]
    end

    %% Operational Flow Edges
    request --> gateway
    gateway --> guardian
    guardian --> executor
    executor --> receipt
    receipt --> collector
    collector --> backend

    %% Premium Styling Rules
    style gateway fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style guardian fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

Operational Readiness

Use this page as the public operating layer for Distributed Tracing. The source of truth is helm-ai-enterprise/docs/public/tracing.md; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, llms-full.txt, and MCP without exposing protected routes.

Validation command: corepack pnpm run docs:coverage && corepack pnpm run docs:truth. For website parity, also run npm run exports:boundary and npm run thin-pages:check from docs-platform.

Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.