pypi / langfuse
langfuse
What changed in langfuse 4 to 5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-20.
66 breaking1 security7 deprecations21 new APIs and options2 performance10 behavior and defaults9 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initlangfuse 563 changes
Breaking changes 39
Previously deprecated public API methods are removed, including api.trace.get/list, api.sessions.*, api.legacy.*, api.ingestion.batch, and several dataset and score methods; use the documented replacements.
The SDK requires Python 3.11 or later; installing it on Python 3.10 installs the latest v4 instead.
fetch_trace_fields is renamed to fields, which defaults to core,basic,io,metadata.
The filter must now be a v2 filter JSON array.
The ingestion batch method is removed; use SDK tracing through OpenTelemetry for traces and api.scores.create for scores.
The api.legacy namespace is removed; use the listed observations, metrics, and scores API replacements.
This method is gone; create scores with api.scores.create(request=[...]) instead.
This method moves to api.scores.delete(score_id=...).
The scores_v3 namespace no longer exists; use api.scores.get_many with the same arguments and response.
Score creation now takes a list of CreateScoreRequest objects as request=; partial acceptance returns accepted and rejected counts and errors.
This method now behaves like scores_v3.get_many_v3; filter by id= for comma-separated score IDs instead of score_ids=.
The sessions API methods are removed; retrieve observations with api.observations.get_many(session_id=...).
Removed; retrieve trace observations with api.observations.get_many(trace_id=...).
This Langfuse argument is removed; combine should_export_span with the default filter instead.
The GenAI check requires the gen_ai. prefix including its dot, so attributes such as gen_ai_custom no longer count.
The dataset run helper is removed; list experiment items and delete their traces with api.trace.delete_multiple instead.
The dataset run helper is removed; use the experiments API instead.
The dataset run helper is removed; use the experiments API instead.
The LangChain integration requires langchain-core 1 or later; importing it with an older version raises ModuleNotFoundError.
The SDK supports Langfuse Cloud or self-hosted Langfuse v4.59.0 or later; self-hosted v3 and older v4 releases are unsupported.
Use this environment variable to set the release instead of the removed
releasetrace attribute.Use this environment variable to set the tracing environment instead of the removed
environmenttrace attribute.Now points to the Metrics v2 endpoint; use the legacy v1 namespace when querying a self-hosted Langfuse v3 server.
Now points to the Observations v2 endpoint; use the legacy v1 namespace when querying a self-hosted Langfuse v3 server.
The v2 score resource is now exposed as
langfuse.api.scores; the v2 alias was removed.Metadata attribute values, including strings, are JSON-encoded; exporters that read or write them should decode with json.loads and encode replacements with json.dumps.
Replaces setting trace publicity through
.updateTrace().Propagated metadata must be a
Record<string, string>; the migration checklist also specifies values of at most 200 characters.The OpenAI integration requires openai 1.0 or later and no longer supports pre-1.0 SDKs.
V4 resume tokens cannot be reused, and resuming with a different filter raises ValueError.
_additional_trace_tags is removed.
Evaluation now reads v2 observations only; fetch_trace_fields becomes fields, filter must be a v2 JSON array, and the mapper receives an observation with raw-string input and output.
Batched evaluation now reads from the v2 observations API and evaluates observations only; scope is removed.
The trace input/output setter is removed; set input and output on the root observation instead.
Replaces setting the trace's
publicattribute throughupdateActiveTrace().OpenTelemetry spans are now filtered by default to Langfuse spans, spans with
gen_ai.*attributes, and spans from known LLM instrumentation scopes.The trace input/output setter is removed; set input and output on the root observation instead.
Set trace input and output on the root observation using span.update(input=..., output=...).
Trace updates are decomposed into attribute propagation, trace I/O setting, and trace-publicity APIs.
Deprecations 2
Deprecated for backward compatibility with trace-level LLM-as-a-judge evaluators.
Deprecated for backward compatibility with trace-level LLM-as-a-judge evaluators; new code should set input/output on the root observation.
New APIs and options 10
Accepts a caller-supplied experiment_id when running an experiment.
Lets custom
shouldExportSpanrules compose with the default span-filtering behavior.Set this environment variable to none if a proxy rejects gzip-compressed span batches.
Provides access to the legacy Metrics v1 API, including for self-hosted Langfuse v3 servers.
Provides access to the legacy Observations v1 API, including for self-hosted Langfuse v3 servers.
Provides access to the legacy Score v1 API.
Dataset versions are recorded on experiment items, including items from local-data runs.
Wraps a callback so the current and child observations created within its scope inherit correlating attributes.
Experiment results now expose an experiment ID that links directly to the experiment comparison view.
Experiment results now expose a URL that links directly to the experiment comparison view.
Performance 1
Tracing skips span attribute limit checks when the span has room, reducing unnecessary checks.
Behavior and default changes 8
Pending scores are sent immediately when flush() is called.
Metadata attribute values, including strings, are JSON-encoded; exporters that read or write them should decode with json.loads and encode replacements with json.dumps.
Scores are sent in batches; partial HTTP 207 rejections and other 4xx responses are logged without retry, while network errors, 429, and 5xx responses are retried with backoff.
Pass a list of CreateScoreRequest objects as request; responses include accepted and rejected counts and errors when some scores are rejected.
The handler now imports only from langchain_core, so the langchain meta-package is no longer needed; its import path and usage are unchanged.
Correlating attributes propagate to every observation instead of living only on the trace, enabling single-table queries without expensive joins.
Experiments are recorded through OpenTelemetry; sampled-out items and their scores do not reach Langfuse when sample_rate is below 1, while run-level scores are always stored.
Metadata sent with v5 preserves numeric and boolean types, and nested objects can be filtered by dotted path.
Fixes and other changes 3
The mapper receives an observation whose input and output are raw strings.
Set otel_compression to none if a proxy rejects gzip-compressed span batches.
Use the default sample_rate=1.0 client for complete experiments.
langfuse 453 changes
Breaking changes 27
The LangChain handler's
update_traceparameter no longer exists; passing it raises aTypeError.Use the Experiment SDK method to run dataset experiments; it handles propagation of experiment attributes and dataset item linking.
The dataset item
run()method was removed; usedataset.run_experiment()to run experiments and handle experiment attribute propagation.getTraceUrl is now asynchronous and returns a promise, so callers should await it.
The package and LangfuseClient class are now for non-tracing features such as scoring, prompt management, and datasets.
Import the Langchain integration from @langfuse/langchain.
Import the OpenAI integration from @langfuse/openai.
Set this environment variable to provide the release value; the
releaseargument toupdate_current_trace()was removed.For Vercel AI SDK integration, replace LangfuseExporter from langfuse-vercel with LangfuseSpanProcessor from @langfuse/otel.
This type is no longer re-exported from
langfuse.types; import it fromlangfuse.modelinstead.Provided tool definitions to the LLM are now mapped to metadata.tools rather than input.tools, which matters when evaluating generations.
This type is no longer re-exported from
langfuse.types; import it fromlangfuse.modelinstead.This TypedDict was removed from
langfuse.types.The SDK no longer exports all OpenTelemetry spans by default; it exports Langfuse-created spans, spans with
gen_ai.*attributes, and spans from known LLM instrumentation scopes.This type is no longer re-exported from
langfuse.types; import it fromlangfuse.modelinstead.Use this context manager to apply correlating attributes to the current observation and all child observations created within its scope.
Propagated metadata must be
dict[str, str]; non-string values are coerced to strings, and values over 200 characters are dropped with a warning.The SDK now requires Pydantic v2; applications still using Pydantic v1 must use the
pydantic.v1compatibility shim.Use this method to set the current trace's public flag, replacing
update_current_trace(public=True).Use this observation method to set the trace's public flag, replacing
span.update_trace(public=True).Observation-level trace updates are decomposed into
propagate_attributes(),set_trace_io(), andset_trace_as_public().This unified context-managed API replaces separate current-span and current-generation methods; use
as_typeto specify the observation type.Use startObservation and related functions from @langfuse/tracing in place of langfuse.trace(), langfuse.span(), and langfuse.generation().
This TypedDict was removed from
langfuse.types.Trace updates are decomposed: use
propagate_attributes()for correlating attributes,set_current_trace_io()for legacy trace I/O, andset_current_trace_as_public()for the public flag.Values are validated as strings with a maximum length of 200 characters; longer values are dropped with a warning.
Pass version as an optional property in the options object to langfuse.prompt.get() instead of as a positional argument.
Security 1
The serializer now masks Pydantic secret values.
Deprecations 5
This option still works but is deprecated; migrate its denylist behavior to a
should_export_spancallback.The Langfuse base URL environment variable is now LANGFUSE_BASE_URL; LANGFUSE_BASEURL remains backward compatible in v4 but will not work in future versions.
LANGFUSE_BASEURL still works for backward compatibility in v4, but will not work in future versions.
This method remains for backward compatibility with trace-level LLM-as-a-judge evaluators; new code should set input and output on the root observation.
This observation method is deprecated; set input and output on the root observation directly for new code.
New APIs and options 11
Adds opt-in gzip compression for the default OTLP exporter.
Import this helper from
langfuse.span_filterto compose custom span filters with the default export behavior.The package is for tracing and provides the LangfuseSpanProcessor used with OpenTelemetry.
The package is for tracing, including the replacement tracing functions.
Set the tracing environment via the LANGFUSE_TRACING_ENVIRONMENT environment variable.
Set the tracing release via the LANGFUSE_TRACING_RELEASE environment variable.
Use this namespace for legacy v1 metrics queries, including when a Python SDK v4 client temporarily queries a self-hosted Langfuse v3 server.
Use this namespace for legacy v1 observation queries, including when a Python SDK v4 client temporarily queries a self-hosted Langfuse v3 server.
Use this namespace for legacy v1 score queries.
Register LangfuseSpanProcessor with an OpenTelemetry NodeSDK to set up tracing in the v4 SDK.
Set this Langfuse client option to control which spans are exported, including preserving export-all behavior or composing a custom filter with the default.
Performance 1
Span processing skips span_formatter when debug logging is off, avoiding unnecessary formatting work.
Behavior and default changes 2
Default exporter batches are capped at 64 MiB.
Values are validated as strings with a maximum length of 200 characters; longer values are dropped with a warning.
Fixes and other changes 6
Dataset JSON-schema response fields are typed as objects.
Read-side metadata is typed as optional objects.
Langfuse now captures reasoning_effort in model parameters.
Langfuse now captures verbosity in model parameters.
NaN/Inf values nested in converted containers are now sanitized during serialization.
The API specification was updated from upstream Langfuse changes.