Troubleshooting

Updated on Aug 14, 2026

Use this article to diagnose common setup, instrumentation, and telemetry issues across supported SDKs.

General Issues

No traces appearing in the platform

Verify your API key is valid. Create a new one if needed.
Check that the endpoint is correct. Default is https://collector.observability.progress.com:443.
Enable debug mode and inspect logs for connection errors.
Call shutdown before process exit to flush buffered spans.

Traces appear but are missing spans

If you use instruments, block_instruments (Python), or blockInstruments (TypeScript), verify the library you want is not excluded.
Decorator-instrumented functions create spans only when you initialize observability before calling those functions.
For the .NET SDK, call AddToolObservability() when you need tool spans.

Tags not showing in the platform

Each tag must be 200 characters or fewer. The platform drops longer tags.
The platform discards empty or whitespace-only tags.

Cost data missing or incorrect

The platform needs the model name in each span to calculate costs.
If the collector pricing database does not contain the model, cost shows as zero.

.NET SDK

ArgumentException on initialization

ObservabilityTracer.Initialize() and AddObservability() require ApiKey to be non-empty; a missing key throws Missing required observability options.
AppName is not required — it defaults to Agent. Two services that both omit it are indistinguishable on the platform, so set it explicitly even though nothing fails.
Endpoint must also be non-empty when explicitly configured.

Tool spans not appearing

With UseFunctionInvocation() or an agent built via AsAIAgent(tools: ...), tool spans are captured automatically when .AddObservability() wraps the chat client — no extra call is needed.
AddToolObservability() is for apps that dispatch tools themselves, outside function-invocation middleware. It is idempotent, so calling it where it is not needed is harmless but adds nothing.

Provider name shows as unknown

The SDK infers the provider from the chat client type name.
With custom or proxy clients, provider detection may fail.

Double-underscore environment variables

Use PROGRESS__OBSERVABILITY__APIKEY with double underscores, not single underscores.

Python SDK

ImportError or ModuleNotFoundError after installing

Verify the package is installed in the expected environment using pip show progress-observability.
The package requires Python >=3.10.0 and <4.0.0.

LLM calls not being traced

Call Observability.instrument() before importing LLM libraries.
If using instruments filtering, ensure enum values match your provider.

Endpoint validation errors

Ensure endpoint includes protocol, host, and valid numeric port.
Use https://host:port format.

API key validation fails at startup

API key must be non-empty.
OBSERVABILITY_API_KEY environment variable takes precedence over the api_key parameter.

My application's own OpenTelemetry stopped working (Python)

If your app calls trace.set_tracer_provider(...) itself and you initialize observability before that call, the app's own registration becomes a no-op. The only signal is one log line:

text

WARNING opentelemetry.trace: Overriding of current TracerProvider is not allowed

Progress traces keep arriving, so everything looks healthy — but the app's own exporter receives nothing. Fix: call Observability.instrument() after the app's own OpenTelemetry setup. See the Python SDK page.

propagate_attributes not working

propagate_attributes requires Observability.instrument() first.
Scoped tags apply only to spans created inside the context block.

TypeScript and JavaScript SDK

ESM hooks warning: ESM hooks not registered

For ESM projects, import @progress/observability/register/hooks before initialization.
Place it at the top of bootstrap or entry file.

LangChain calls not traced

In ESM mode, import LangChain modules dynamically after Observability.instrument().
Static imports before instrument() can bypass instrumentation.

Decorators not working

TypeScript decorators apply to class methods, not standalone functions.
Use wrapFunctionWithSpan() for standalone function instrumentation.
Ensure tsconfig enables experimentalDecorators when using legacy decorators.

Process hangs on exit

Call await Observability.shutdown() to flush spans and release resources.

Traces only show partial data

If traceContent is false, prompts and completions are intentionally excluded.
The SDK may clear conflicting OTEL_* environment variables during setup.

NU1605 package downgrade on install (.NET)

Progress.Observability.Instrumentation depends on OpenTelemetry NuGet packages. If your project pins an older OpenTelemetry version, dotnet add package fails with NU1605: Detected package downgrade: OpenTelemetry. Raise your project's OpenTelemetry reference first.