Getting Started

Troubleshooting

Troubleshooting

Updated on Jun 16, 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 AppName and ApiKey to be non-empty.
Endpoint must also be non-empty when explicitly configured.

Tool spans not appearing

Call AddToolObservability() on ChatOptions or the tool list.
For IAgent, tools wrapped with AIFunctionFactory are not instrumented automatically.

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.

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.

See Also