Tracing and lifecycle

Evaluate and observe separately

Direct evaluation can create its own decision trace. Instrumentation records model and framework operations. A pre-call SDK check uses no_trace to avoid recording a duplicate evaluation trace; model tracing must be enabled separately.

A span received after a tool or model operation cannot prevent that operation. Never use successful export as evidence of enforcement.

Python instrumentation

python -m pip install "nyraxis-sdk[instrument]==1.3.2" openai

import os
import nyraxis_sdk
from openai import OpenAI

nyraxis_sdk.init(
    api_key=os.environ["NYRAXIS_API_KEY"],
    base_url=os.environ["NYRAXIS_BASE_URL"],
    agent_name="support-agent",
    instrument=True,
    instrument_capture_content=False,
)
try:
    with nyraxis_sdk.trace("support-turn", environment="development"):
        response = OpenAI().chat.completions.create(
            model=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),
            messages=[{"role": "user", "content": "Say hello to a synthetic user."}],
        )
    if not nyraxis_sdk.flush(timeout_millis=30_000):
        raise RuntimeError("Exporter did not finish in time")
finally:
    nyraxis_sdk.shutdown()

instrument=True configures a supported Traceloop/OpenTelemetry path to {base_url}/api/v1/ingest/otel with the issued key. Verify your exact instrumentor versions. trace() only creates a parent; it does not invent child spans for uninstrumented calls.

The live LangGraph example produced model spans with token counts and a tool span. Parent and step spans keep the execution structure even when their content and interpolated names are withheld.

Data handling

Set instrument_capture_content=False before instrumenting when prompts and completions should be suppressed in telemetry attributes. It requests Traceloop content suppression; test the actual serialized spans for your instrumentors.

The backend's organization capture setting is a separate ceiling. Metadata-only storage removes prompt/output fields and can replace names containing workload content. Direct evaluate() still sends its input and output to the configured evaluator. Read data handling.

Manual tracing

Python's trace() and @traced() can use an application-owned OpenTelemetry provider even with instrument=False. Install and configure the provider, OTLP exporter, and processor yourself. Without a configured provider/exporter, wrapping a function does not establish a stored trace.

Node exports trace and traced; the application owns telemetry setup in every case. Attach an OTLP/HTTP exporter to /api/v1/ingest/otel using X-API-Key. Do not put credentials into span attributes.

Streaming

Python generator and async-generator decorators keep a parent span alive during consumption. Node 1.2.9 preserves supported stream lifetimes and caller context. Close partially consumed streams with the API supplied by that stream: Python close()/aclose(), Node iterator return(), stream cancellation, or the provider's abort method.

A pre-call input check can run before a stream begins. It does not inspect and block every output token. To require an output decision before release, buffer the complete response, evaluate it, and release only after a complete allowed decision. This changes the latency and streaming experience.

Shutdown and receipt

1. Stop accepting new work.
2. Finish or cancel producers and close open streams.
3. Python: call shutdown() or await shutdown_async(). Node: flush and shut down your application-owned telemetry pipeline.
4. Verify the trace in the backend. Check parent/child relationships, model metadata, capture mode, and any findings.

flush() returning true means a flush completed; exporters may still have reported transport errors. Durable backend receipt is the acceptance check.

Troubleshoot missing spans

• Confirm an ingest-scoped key, the backend origin, and the /api/v1/ingest/otel destination.
• Check that a real provider is registered and that its instrumentor supports the model method.
• Keep the process alive until producers end and export completes.
• Search by the trace ID, then the correct agent and organization.
• Inspect exporter errors without printing headers, prompts, or response bodies.