Control trace privacy

SDK 0.6.0 atlanai SDK sends span payloads such as prompts, completions, and tool arguments to Atlan Trident by default. Atlan Trident stores that content unless an organization admin turns off session-content storage; when storage is off, it drops the content and keeps usage, cost, and timing. Use these controls when payloads contain data that must not leave your environment, or when you need to cut export volume; all three fail closed, so when one breaks, data is withheld rather than leaked.

Before you begin

Before you start, make sure you have:

SDK: atlanai SDK installed with tracing, as in Install atlanai SDK.
Tracing: a working init call that exports traces, as in Trace your first agent run.
Decision: which data must stay out of traces. Suppress all content when payloads must never leave, mask specific values when you need most content, and sample when you need fewer traces.

The steps below are alternatives. Set every option you need in one init call: a later call with the same API key, endpoint, workspace, service name, agent ID, and tracing mode returns the first client and ignores its other options.

Suppress payload content

Set trace_content to false. The SDK stops recording input, output, metadata, and tool payloads, and keeps span names, observation types, model, provider, usage, cost, and scores.It also keeps two attributes that are not content: atlan.skill.name, the skill a tool call invoked, and atlan.run.retry, which marks a run that retries an earlier, failed run of the same agent. The TypeScript pi instrumentation writes both.

Python
TypeScript

from atlanai.tracing import init

client = init(service_name="support-rover", trace_content=False)

import { init } from "@atlanai/sdk/tracing";

const client = init({ serviceName: "support-rover", traceContent: false });

ATLAN_TRACE_CONTENT=false does the same without a code change. It also sets atlan.consent.store_content=false on the resource, so the gateway enforces the same decision on the server side.

Mask specific values

To redact parts of content instead of suppressing all of it, pass a mask hook. It runs when your own spans record input, output, and metadata, receives the value, and returns the redacted replacement.

Python
TypeScript

def mask(*, data, **_):
    return redact_pii(data)

client = init(service_name="support-rover", mask=mask)

Accept extra keyword arguments (**_) so the hook keeps working if a later version passes more context.

const client = init({
  serviceName: "support-rover",
  mask: ({ data }) => redactPii(data),
});

If the hook raises, the SDK replaces the value with [atlan: value withheld - mask hook failed] instead of sending it unmasked.mask only sees spans the SDK created. Spans from third-party instrumentation such as OpenLLMetry, OpenInference, or a framework’s native OpenTelemetry bypass it. To reach those spans, pass mask_otel_spans (Python) or maskOtelSpans (TypeScript). It runs over each export batch and returns a patch per span that deletes attributes or sets replacement values. Return no patch for a span to leave it unchanged.

Python
TypeScript

from atlanai.tracing import OtelSpanPatch

def mask_otel_spans(params):
    return {
        ident: OtelSpanPatch(delete_attributes=["gen_ai.input.messages"])
        for ident, span in params.items()
        if "gen_ai.input.messages" in span.attributes
    }

client = init(service_name="support-rover", mask_otel_spans=mask_otel_spans)

const client = init({
  serviceName: "support-rover",
  maskOtelSpans: (spans) => {
    const patches = new Map();
    for (const [key, span] of spans) {
      if ("gen_ai.input.messages" in span.attributes) {
        patches.set(key, { deleteAttributes: ["gen_ai.input.messages"] });
      }
    }
    return patches;
  },
});

A failing batch hook drops data, because a partial result cannot be trusted. If the hook raises or returns an invalid shape, the whole batch is dropped. If one patch is invalid, that single span is dropped. Dropped spans are lost traces, so test the hook against representative spans before production.

Reduce trace volume

Two independent controls reduce what is exported.

Sampling: set sample_rate (Python) or sampleRate (TypeScript) between 0.0 and 1.0, or set ATLAN_SAMPLE_RATE. A value outside that range is ignored with a warning and treated as 1.0.
Export allowlist: by default the SDK exports its own spans and spans from recognized GenAI instrumentors, and drops unrelated application spans. Pass should_export_span or shouldExportSpan to replace that decision entirely.

Sampling applies only when the SDK creates the TracerProvider. If your application owns the provider, configure sampling on that provider.

Isolate from other tracing vendor

This step is optional and applies to TypeScript. If you already export to Langfuse, Braintrust, or another OpenTelemetry backend, set isolated: true. The SDK stays off the global TracerProvider and runs a private pipeline, so neither vendor receives the other’s spans.

const client = init({ serviceName: "support-rover", isolated: true });

To send Atlan spans through a provider your application owns, pass client.spanProcessor into that provider’s constructor instead.

Verify controls

Run one request, call flush(), and open the trace in Atlan Trident.

With trace_content off, spans show names, model, usage, and cost, with no input or output.
With a mask, the redacted replacement appears where the original value was.
After deploying a batch hook, watch application logs for dropping batch warnings.

If no traces appear at all, see init() disables tracing and no traces are exported.

Troubleshooting

If a masked or suppressed value still appears, or traces stop appearing after you add a hook, see Install and setup errors.

Next steps

Export traces from serverless: flush reliably when the process is short-lived.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Before you begin

Troubleshooting

Next steps

See also