API reference

Complete list of all public symbols exported from semantic_tracing and semantic_tracing.trace_reader, plus the source file layout.

Public API

Symbol	Kind	Description
`setup_tracing()`	function	One-time process init — wires Langfuse as the global OTel TracerProvider. See 01-tracing-setup.md.
`Release`	dataclass	What produced a trace: `id`, optional `instructions_version` and `knowledge_version`. The SDK writes `id` to Langfuse's release field and all three to trace metadata as `release_id`, `instructions_version` and `knowledge_version`, the keys `semantic_evaluation`'s `run_config` reserves for a release service. See 01-tracing-setup.md.
`set_release(release)`	function	Makes a `Release` (or None to clear) the release of every trace whose root starts afterwards. See 01-tracing-setup.md.
`InputFilter`	dataclass	Global rules for stripping named or typed arguments from `@step` inputs. See 04-tracing-input-capture.md.
`@step(name)`	decorator	Wraps a function as a Langfuse observation. See 02-tracing-observations.md.
`update_current_step()`	function	Attach runtime metadata, output, level, model, usage, completion_start_time, or usage_details to the active observation. See 02-tracing-observations.md and 03-tracing-generation.md.
`span(name)`	context manager	Wraps a code block as a Langfuse observation. See 02-tracing-observations.md.
`event(name)`	function	Single point-in-time marker with no duration. See 02-tracing-observations.md.
`propagate()`	context manager	Stamps all child spans with `user_id`, `session_id`, `tags`, `metadata` and `version`; a reserved release key in `metadata` overrides the release for that request. Also populates `TRACE_CONTEXT` with the active App Insights request span context so `link_app_insights_to_langfuse()` needs no arguments. See 02-tracing-observations.md.
`TraceContext`	dataclass	Per-request cross-backend identifiers: `langfuse_trace_id`, `app_insights_operation_id`, `app_insights_request_span_id`. Populated by `propagate()`. See 11-tracing-app-insights-langfuse-cross-reference.md.
`TRACE_CONTEXT`	`ContextVar[TraceContext \\| None]`	Active cross-backend context for the current request scope; access via `get_trace_context()`. See 11-tracing-app-insights-langfuse-cross-reference.md.
`get_trace_context()`	function	Convenience accessor for `TRACE_CONTEXT.get()`; returns `None` outside a `propagate()` scope or when the App Insights span was not valid at entry time. See 11-tracing-app-insights-langfuse-cross-reference.md.
`record_first_token()`	function	Stamps the active `@step` span with `completion_start_time=now()` for TTFT tracking. See 03-tracing-generation.md.
`wrap_azure_stream(stream)`	async generator	Wraps an OpenAI/Azure OpenAI streaming response; records TTFT and usage automatically. See 03-tracing-generation.md.
`resume_trace(key)`	context manager	Every observation started in scope joins the trace `key` names, under that trace's root. For a unit of work that spans several requests. See 13-tracing-across-requests.md.
`record_trace_root(key, name, *, start_time, ...)`	function	Records the root observation `key` names, with caller-supplied times; recording again under the same key updates it. See 13-tracing-across-requests.md.
`record_observation(name, *, start_time, end_time, ...)`	function	Records work that already happened, with its own times, under the current parent. See 13-tracing-across-requests.md.
`derived_ids(key)`	function	The trace id and root observation id `key` resolves to, as hex. See 13-tracing-across-requests.md.
`get_trace_id()`	function	Returns the current Langfuse trace ID, or `None` if no active trace.
`get_observation_id()`	function	Returns the current Langfuse observation (span) ID, or `None`.
`get_tracer(name)`	function	Returns the underlying OTel `Tracer` from the global provider. Low-level; use when you need to create OTel-native spans that participate in the same trace tree. Most callers do not need this.
`flush()`	function	Sends all buffered observations to Langfuse synchronously. Call before process exit or test teardown.
`get_langchain_callback()`	function	Returns a LangChain `CallbackHandler` that nests LangChain spans under the active OTel context. See 05-tracing-frameworks.md.
`ObservationType`	type alias	`Literal` union of all valid `as_type` values. See the table below.
`fetch_trace(trace_id, *, backoff=...)`	async function	Poll Langfuse for a finished trace; returns once observations are populated. See 07-tracing-reader.md.
`find_observations(trace, *, name=None, name_in=None)`	function	Filter trace observations by name or allow-set, preserving order. See 07-tracing-reader.md.
`as_dict(value)`	function	Coerce a Langfuse JSON-or-dict field to a plain `dict`. See 07-tracing-reader.md.
`coerce_text(value, *, prefer_keys=())`	function	Coerce a Langfuse output payload to a single string. See 07-tracing-reader.md.
`LocalTrace`	class	In-process trace mirror; `.observations: list[LocalObservation]`. See 12-tracing-local-capture.md.
`LocalObservation`	class	One captured span; `.name`, `.input`, `.output`, `.attributes`, `.metadata`. See 12-tracing-local-capture.md.
`get_local_trace(trace_id)`	function	Retrieve a captured trace by ID from the in-process store, or `None`. See 12-tracing-local-capture.md.
`local_trace_from_dict(data)`	function	Deserialize a `LocalTrace` from `.to_dict()` output. See 12-tracing-local-capture.md.
`fetch_local_trace_via_http(url, *, client=None)`	async function	GET a pod-supplied debug endpoint and deserialize the response as a `LocalTrace`. See 12-tracing-local-capture.md.
`get_app_insights_query_url(kql, ...)`	function	Build an Azure Portal Log Analytics deep-link URL for a KQL query, scoped to the pod's App Insights resource. Returns `None` when `APP_INSIGHTS_RESOURCE_ID` or `APP_INSIGHTS_TENANT_ID` are absent. See 11-tracing-app-insights-langfuse-cross-reference.md.
`link_app_insights_to_langfuse(...)`	function	Stamp cross-reference attributes on both the App Insights request span (`langfuse.trace_id`, `langfuse.trace_url`) and the active Langfuse chain observation (`app_insights.request_span_id`, `app_insights.query_url`). All arguments optional — defaults read from context set by `propagate()`. See 11-tracing-app-insights-langfuse-cross-reference.md.
`resolve_langfuse_trace_url_prefix()`	function	Deprecated since v0.3.5. No longer required; retained for backward compatibility. `link_app_insights_to_langfuse()` resolves and caches the prefix automatically. Emits `DeprecationWarning`.

ObservationType values

ObservationType = Literal[
    "span",        # generic duration — default when as_type is omitted
    "generation",  # LLM call — activates token usage, cost tracking, and TTFT
    "embedding",   # embedding model call — supports token usage
    "agent",       # agent making routing or generation decisions
    "tool",        # tool or external API call
    "chain",       # link between steps passing context
    "retriever",   # vector store or database retrieval
    "evaluator",   # assessment function
    "guardrail",   # content safety or validation check
]

Source file layout

File	Responsibility
`setup.py`	`setup_tracing()`: provider unification, environment, release, span-name sampler, sensitive-data toggle, Agent Framework token usage patches
`release.py`	`Release`, `set_release()`, the process's current release
`decorators.py`	`@step`, `update_current_step`, `ObservationType`
`context.py`	`span()`, `event()`, `propagate()`
`generation.py`	`record_first_token()`, `wrap_azure_stream()`
`ids.py`	`get_trace_id()`, `get_observation_id()`, `get_tracer()`, `flush()`
`adapters.py`	`get_langchain_callback()`
`filtering.py`	`InputFilter`, argument filtering logic
`trace_reader.py`	`fetch_trace`, `find_observations`, `as_dict`, `coerce_text`
`local_capture.py`	`LocalTrace`, `LocalObservation`, `LocalTraceCaptureProcessor`, `get_local_trace`, `local_trace_from_dict`, `fetch_local_trace_via_http`
`_app_insights.py`	`get_app_insights_query_url()`, `link_app_insights_to_langfuse()`, `resolve_langfuse_trace_url_prefix()` (deprecated)
`resumed.py`	`resume_trace()`, `record_trace_root()`, `record_observation()`, `derived_ids()`, the seeded id generator
`_trace_context.py`	`TraceContext`, `TRACE_CONTEXT`, `get_trace_context()`
`docs.py`	`python -m semantic_tracing.docs`: the documentation shipped in the wheel
`pricing/`	`python -m semantic_tracing.pricing`: Azure deployments priced in Langfuse. The command and its subcommands are the interface; the modules behind it are private. See 14-tracing-model-prices.md

Version policy

semantic-tracing follows semantic versioning. Backward compatibility is guaranteed within a major version.

Release	Contract
PATCH (`x.y.z → x.y.z+1`)	Bug fix, no API change — drop-in replacement
MINOR (`x.y → x.y+1`)	New capability added — existing callers work without changes
MAJOR (`x → x+1`)	Breaking change — documented in CHANGELOG; callers must update

The public API for this guarantee is every symbol listed in the Public API table above and every parameter documented in this docs/ folder. Internal modules and undocumented helpers carry no compatibility guarantee.

Declare a version constraint in pyproject.toml to receive patch and minor updates automatically while being protected from breaking major-version changes:

[project]
dependencies = [
    "semantic-tracing>=0.2.2,<1",
]

Or via uv:

uv add "semantic-tracing>=0.2.2,<1"