Skip to content

Configuration & Sensitivity

Tracy offers flexible configuration options to control how traces are collected and exported and how sensitive data is handled.

TracingManager

The TracingManager is the central configuration point for the library.

Method/Property Description
setSdk(sdk: OpenTelemetrySdk) Sets the OpenTelemetry SDK instance
isTracingEnabled: Boolean Runtime toggle for tracing (defaults to IS_TRACY_ENABLED env var)
flushTraces(timeoutSeconds: Long = 5) Forces flushing of pending spans
shutdownTracing(timeoutSeconds: Long = 5) Shuts down the OpenTelemetry SDK
traceSensitiveContent() Enables capturing of inputs and outputs
withCapturingPolicy(policy: ContentCapturePolicy) Sets custom content capture policy

Enabling/Disabling Tracing

You can enable or disable tracing at runtime:

TracingManager.isTracingEnabled = true // Enable
TracingManager.isTracingEnabled = false // Disable

By default, it checks the IS_TRACY_ENABLED environment variable.

Setting the SDK

Before any spans can be exported, you must set an OpenTelemetry SDK instance. For detailed SDK configuration options, see SDK Configuration.

val sdk = configureOpenTelemetrySdk(ConsoleExporterConfig())
TracingManager.setSdk(sdk)

Sensitive Content (Redaction)

According to OpenTelemetry Generative AI Semantic Conventions, capturing sensitive data like user messages or assistant replies should be disabled by default.

Tracy follows this convention and replaces sensitive content with the placeholder "REDACTED" by default.

Enabling Content Capture

You can enable capturing of inputs and outputs in two ways:

1. Environment Variables

Set the following environment variables:

TRACY_CAPTURE_INPUT=true
TRACY_CAPTURE_OUTPUT=true

2. Programmatically

Use the helper method to enable both:

TracingManager.traceSensitiveContent()

Or configure the policy more granularly:

TracingManager.withCapturingPolicy(
    ContentCapturePolicy(
        captureInputs = true,
        captureOutputs = false // Only capture inputs
    )
)

Exporters

Tracy supports multiple backends out of the box. For detailed configuration, see Exporters.

  • Langfuse: Dedicated LLM observability platform.
  • Weave (Weights & Biases): For experiment tracking and evaluation.
  • OTLP HTTP: Export to any OpenTelemetry-compliant backend (Jaeger, Grafana Tempo, etc.).
  • Console: Great for development and debugging.
  • File: Export traces to a local JSON or plain text file.

Flushing and Shutdown

Automatic Flushing

Tracy automatically flushes traces in two ways:

  1. Periodic batch flushing: Spans are automatically exported in batches based on the ExporterCommonSettings configuration:

    • flushIntervalMs (default: 5ms) — delay between batch export attempts
    • flushThreshold (default: 512) — maximum number of spans per export batch

  2. Shutdown flushing: When the application exits, Tracy flushes and shuts down traces via a JVM shutdown hook. This is enabled by default through the flushOnShutdown setting (default: true).

Manual Flushing

For cases where you need manual control (e.g., reading trace files before exit, or when flushOnShutdown is disabled), you can use flushTraces() or shutdownTracing():

// Flush pending spans (waits up to 5 seconds by default)
TracingManager.flushTraces()

// Or with custom timeout
TracingManager.flushTraces(timeoutSeconds = 10)

// For graceful shutdown (flushes and releases resources)
TracingManager.shutdownTracing()