perf(tracing): skip span attribute limit checks when the span has room

[DavidTraina]

What does this PR do?

Follow-up to #1957.

Almost every SDK attribute write runs _drop_attributes_over_span_limit. That covers observation creation, update(), propagate_attributes, LangfuseSpanProcessor.on_start for every span with propagated attributes, and the root markers. Each call checked key not in span.attributes for every new key and every reserved key (7 or 14). span.attributes is a MappingProxyType over OTel's BoundedAttributes, which has no __contains__. Each miss goes through Mapping.__contains__, which raises and catches a KeyError. This ran on every write, even on spans far below the 128-attribute limit, and on the caller's thread, which is the event loop in async apps.

Changes, all in langfuse/_client/span.py:

• Return early when len(existing) + len(attributes) + len(reserved_keys) <= max_attributes. This is an upper bound of the exact count the guard already computes, so it cannot change a drop decision.
• On the slow path, snapshot the existing keys into a set once instead of probing the proxy per key.
• Precompute the span-like observation types into a frozenset instead of flattening the Literal on every call.
• Write type, environment and release in LangfuseObservationWrapper.__init__ in one guarded call instead of three. The kept keys and their order are the same.

Final span attributes, drop order, warning text and the never-raises contract are unchanged. Log output can differ only for the batched write in __init__ on a span with fewer than three free slots. There it logs at most one limit warning, where the three separate writes logged one per dropped key. On a span that has already ended, which ignores the write anyway, it can log one limit warning where main logged none.

Benchmark

Thread CPU time per operation on the caller thread, with a null exporter and no network. Each value is the median over 12 runs per checkout, alternating which checkout runs first. Environment: Apple M5 Max, Python 3.14.5, OTel SDK 1.45.0, client configured with environment and release. The machine was under load, so absolute numbers are inflated. The direction of each change was consistent across runs.

Scenario	main (us)	this PR (us)	change
start_observation(input, 15 metadata keys) + update(output) + end	79.4	61.5	-22%
root + propagate_attributes + child generation with update	148.8	97.5	-34%
start_observation(input, 118 metadata keys) + update(output) + end (slow path, nothing dropped)	196.5	174.7	-11%
_drop_attributes_over_span_limit, 1 key, span with 20 attributes	2.5	0.3	-89%
update(output) on a span with 124 attributes	9.9	10.9	+10%
_drop_attributes_over_span_limit, 1 key, span with 124 attributes	2.5	2.5	-1%

Without environment and release configured, the first two scenarios improved by 33% and 23% over 8 runs.

The trade-off is on spans close to the limit. A small write takes the slow path once the span is within about 8 attributes of the limit for span-like observations, or about 15 for generations. The slow path now copies the existing keys into a set. For a small write such as update(output), that costs about 1 us more than probing a few keys. For a large write near the limit, it saves much more, as the 118-key row shows.

Benchmark script

Run it from outside the repo with PYTHONPATH=<checkout> python bench_attr_limit.py, so langfuse is imported from that checkout.

"""Caller-thread CPU cost of Langfuse observation writes, null exporter, no network.

Prints one JSON line with the median thread CPU time per operation in
microseconds, over batches of BATCH operations. Run it once per checkout, e.g.
PYTHONPATH=<checkout> python bench_attr_limit.py. Set BENCH_NO_ENV=1 to run
without a client environment and release.
"""

import gc
import json
import os
import statistics
import sys
import time

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult

from langfuse import Langfuse, propagate_attributes
from langfuse._client.span import _drop_attributes_over_span_limit

N = int(sys.argv[1]) if len(sys.argv) > 1 else 5000
BATCH = 20


class NullExporter(SpanExporter):
    def export(self, spans):
        return SpanExportResult.SUCCESS

    def shutdown(self):
        pass


client = Langfuse(
    public_key="pk-lf-bench",
    secret_key="sk-lf-bench",
    base_url="http://127.0.0.1:9",
    tracer_provider=TracerProvider(),
    span_exporter=NullExporter(),
    flush_at=2048,
    flush_interval=3600,
    **(
        {}
        if os.environ.get("BENCH_NO_ENV")
        else {"environment": "production", "release": "v1"}
    ),
)

METADATA_15 = {f"key_{i}": f"value_{i}" for i in range(15)}
METADATA_118 = {f"key_{i}": f"value_{i}" for i in range(118)}


def observation_with_metadata_and_update():
    span = client.start_observation(name="obs", input="in", metadata=METADATA_15)
    span.update(output="out")
    span.end()


def root_propagate_child_generation():
    with client.start_as_current_observation(name="root", input="in"):
        with propagate_attributes(
            user_id="user", session_id="session", metadata={"tenant": "t"}
        ):
            generation = client.start_observation(
                name="gen", as_type="generation", model="m", input="in"
            )
            generation.update(output="out", usage_details={"input": 1, "output": 2})
            generation.end()


def observation_near_limit_and_update():
    span = client.start_observation(name="big", input="in", metadata=METADATA_118)
    span.update(output="out")
    span.end()


_span = client.start_observation(name="guard", input="in", metadata=METADATA_15)
_otel_span = _span._otel_span


def guard_one_key():
    _drop_attributes_over_span_limit(_otel_span, {"langfuse.observation.output": "x"})


_full_span = client.start_observation(
    name="full",
    input="in",
    metadata={
        f"key_{i}": "v" for i in range(124 - (len(_otel_span.attributes) - 15) - 1)
    },
)
_full_span.update(output="out")
_full_otel_span = _full_span._otel_span
assert len(_full_otel_span.attributes) == 124, len(_full_otel_span.attributes)


def update_output_on_full_span():
    _full_span.update(output="out")


def guard_one_key_on_full_span():
    _drop_attributes_over_span_limit(
        _full_otel_span, {"langfuse.observation.output": "x"}
    )


SCENARIOS = {
    "start_observation(input, 15 metadata keys) + update(output) + end": (
        observation_with_metadata_and_update
    ),
    "root + propagate_attributes + child generation with update": (
        root_propagate_child_generation
    ),
    "start_observation(input, 118 metadata keys) + update(output) + end": (
        observation_near_limit_and_update
    ),
    "_drop_attributes_over_span_limit, 1 key, span with 20 attributes": (guard_one_key),
    "update(output) on a span with 124 attributes": update_output_on_full_span,
    "_drop_attributes_over_span_limit, 1 key, span with 124 attributes": (
        guard_one_key_on_full_span
    ),
}


def measure(fn):
    timings = []
    for i in range(N // BATCH):
        if i % 25 == 0:
            client.flush()
        start = time.thread_time_ns()
        for _ in range(BATCH):
            fn()
        timings.append((time.thread_time_ns() - start) / BATCH)
    client.flush()
    return statistics.median(timings) / 1000


for fn in SCENARIOS.values():
    for _ in range(200):
        fn()

results = {}
for name, fn in SCENARIOS.items():
    gc.collect()
    results[name] = measure(fn)

print(json.dumps(results))

Type of change

• Bug fix
• New feature
• Breaking change
• Refactor
• Documentation update
• Tooling, CI, or repo maintenance

Verification

List the main commands you ran:

uv run --frozen ruff check .                                # All checks passed!
uv run --frozen ruff format --check .                      # 575 files already formatted
uv run --frozen mypy langfuse --no-error-summary            # no errors
uv run --frozen pytest -n auto --dist worksteal tests/unit  # 923 passed, 2 skipped

New tests:

• test_metadata_budget_is_exact_at_the_limit pins the metadata budget at the exact limit. It includes overwrites and reserved keys that are already on the span or in the same write. An early return that is too loose by one fails it, and no existing test catches that.
• test_environment_and_release_are_set_only_when_configured checks that type, environment and release land on the span, and that unset environment and release stay absent. OTel 1.45 stores None attribute values, so passing them into the batched write would fail this test.
• test_observation_type_is_kept_when_environment_and_release_do_not_fit builds an observation on a span with one free slot. It checks that the observation type is kept and that a single warning names environment and release. A different key order in the batched write fails it.
• The first two tests also pass against span.py from main. The third gets the same attributes on main but fails on the warning count, since main logs two warnings there.

test_hard_guard_never_raises now raises from __iter__ instead of __contains__, because the slow path iterates the attributes once instead of probing them.

Not run: tests/e2e and tests/live_provider, which need a server and provider keys. This change has no network behavior.

Checklist

• I self-reviewed the diff using code_review.md.
• I added or updated tests for behavior changes.
• I updated docs, examples, or .env.template if needed. (n/a, internal-only change)
• I did not hand-edit generated files; if generated files changed, I used the upstream regeneration path.
• I did not commit secrets or credentials.

Confidence Score: 5/5

The PR appears safe to merge; no actionable issues were found.

Summary

This PR reduces work when writing span attributes.

• Span attribute writes skip detailed checks when the span has room.
• Observation setup writes its initial attributes together.

No actionable issues found. Tests were inspected but not run during this review.

DavidTraina explicitly acknowledged fewer warnings for batched drops and a possible extra limit warning on an ended span. These intentional differences were not reported.

_{Reviews (1) · Last reviewed commit: "test: keep the observation type when env..." · Reviewed by Greptile}

What does this PR do?

Follow-up to #1957. Original analysis, fix, tests and benchmark by @DavidTraina.

Almost every SDK attribute write runs _drop_attributes_over_span_limit. That covers observation creation, update(), propagate_attributes, LangfuseSpanProcessor.on_start for every span with propagated attributes, and the root markers. Each call checked key not in span.attributes for every new key and every reserved key (7 or 14). span.attributes is a MappingProxyType over OTel's BoundedAttributes, which has no __contains__. So each miss goes through Mapping.__contains__, which raises and catches a KeyError. This ran on every write, even on spans far below the 128-attribute limit, and on the caller's thread, which is the event loop in async apps.

The change is in langfuse/_client/span.py. It returns early when the span clearly has room:

existing = getattr(span, "attributes", None) or {}
# Upper bound of the exact count below: if it fits, nothing is dropped.
if len(existing) + len(attributes) + len(reserved_keys) <= max_attributes:
    return attributes

Each term is at least as large as its counterpart in the exact count the guard already computes. That count covers new non-None keys not on the span, and reserved keys neither on the span nor in the write. So the early return can't change a drop decision. Spans near the limit take the existing path unchanged. Final attributes, drop order, warning text, warning count and the never-raises contract are identical to main.

The first version of this PR also snapshotted the existing keys into a set on the slow path, precomputed the span-like observation types, and batched the type, environment and release writes in LangfuseObservationWrapper.__init__. These were dropped for simplicity. The early return carries almost all of the gain on common paths, and without the batched write the log output matches main exactly. The extras mainly helped metadata-heavy spans near the limit (about −14% vs −4% in the 118-key row), plus about 7 µs per observation when environment and release are configured.

Benchmark

Thread CPU time per operation on the caller thread, with a null exporter and no network, using David's script below. Linux VM, Python 3.13, OTel SDK 1.45.0. Each value is the median over 8 alternating runs per checkout, with the client configured with environment and release.

Scenario	main (us)	this PR (us)	change
start_observation(input, 15 metadata keys) + update(output) + end	111.7	88.5	-21%
root + propagate_attributes + child generation with update	229.0	165.3	-28%
start_observation(input, 118 metadata keys) + update(output) + end	287.0	276.3	-4%
_drop_attributes_over_span_limit, 1 key, span with 20 attributes	4.6	0.4	-90%
update(output) on a span with 124 attributes	11.0	11.1	+1%
_drop_attributes_over_span_limit, 1 key, span with 124 attributes	4.8	5.0	+3%

Without environment and release (BENCH_NO_ENV=1, 3 runs), the first two scenarios improved by 17% and 24%. The two rows near the limit are within noise of main, as expected, since they take the same path.

Benchmark script (by @DavidTraina)

Run it from outside the repo with PYTHONPATH=<checkout> python bench_attr_limit.py, so langfuse is imported from that checkout.

"""Caller-thread CPU cost of Langfuse observation writes, null exporter, no network.

Prints one JSON line with the median thread CPU time per operation in
microseconds, over batches of BATCH operations. Run it once per checkout, e.g.
PYTHONPATH=<checkout> python bench_attr_limit.py. Set BENCH_NO_ENV=1 to run
without a client environment and release.
"""

import gc
import json
import os
import statistics
import sys
import time

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult

from langfuse import Langfuse, propagate_attributes
from langfuse._client.span import _drop_attributes_over_span_limit

N = int(sys.argv[1]) if len(sys.argv) > 1 else 5000
BATCH = 20


class NullExporter(SpanExporter):
    def export(self, spans):
        return SpanExportResult.SUCCESS

    def shutdown(self):
        pass


client = Langfuse(
    public_key="pk-lf-bench",
    secret_key="sk-lf-bench",
    base_url="http://127.0.0.1:9",
    tracer_provider=TracerProvider(),
    span_exporter=NullExporter(),
    flush_at=2048,
    flush_interval=3600,
    **(
        {}
        if os.environ.get("BENCH_NO_ENV")
        else {"environment": "production", "release": "v1"}
    ),
)

METADATA_15 = {f"key_{i}": f"value_{i}" for i in range(15)}
METADATA_118 = {f"key_{i}": f"value_{i}" for i in range(118)}


def observation_with_metadata_and_update():
    span = client.start_observation(name="obs", input="in", metadata=METADATA_15)
    span.update(output="out")
    span.end()


def root_propagate_child_generation():
    with client.start_as_current_observation(name="root", input="in"):
        with propagate_attributes(
            user_id="user", session_id="session", metadata={"tenant": "t"}
        ):
            generation = client.start_observation(
                name="gen", as_type="generation", model="m", input="in"
            )
            generation.update(output="out", usage_details={"input": 1, "output": 2})
            generation.end()


def observation_near_limit_and_update():
    span = client.start_observation(name="big", input="in", metadata=METADATA_118)
    span.update(output="out")
    span.end()


_span = client.start_observation(name="guard", input="in", metadata=METADATA_15)
_otel_span = _span._otel_span


def guard_one_key():
    _drop_attributes_over_span_limit(_otel_span, {"langfuse.observation.output": "x"})


_full_span = client.start_observation(
    name="full",
    input="in",
    metadata={
        f"key_{i}": "v" for i in range(124 - (len(_otel_span.attributes) - 15) - 1)
    },
)
_full_span.update(output="out")
_full_otel_span = _full_span._otel_span
assert len(_full_otel_span.attributes) == 124, len(_full_otel_span.attributes)


def update_output_on_full_span():
    _full_span.update(output="out")


def guard_one_key_on_full_span():
    _drop_attributes_over_span_limit(
        _full_otel_span, {"langfuse.observation.output": "x"}
    )


SCENARIOS = {
    "start_observation(input, 15 metadata keys) + update(output) + end": (
        observation_with_metadata_and_update
    ),
    "root + propagate_attributes + child generation with update": (
        root_propagate_child_generation
    ),
    "start_observation(input, 118 metadata keys) + update(output) + end": (
        observation_near_limit_and_update
    ),
    "_drop_attributes_over_span_limit, 1 key, span with 20 attributes": (guard_one_key),
    "update(output) on a span with 124 attributes": update_output_on_full_span,
    "_drop_attributes_over_span_limit, 1 key, span with 124 attributes": (
        guard_one_key_on_full_span
    ),
}


def measure(fn):
    timings = []
    for i in range(N // BATCH):
        if i % 25 == 0:
            client.flush()
        start = time.thread_time_ns()
        for _ in range(BATCH):
            fn()
        timings.append((time.thread_time_ns() - start) / BATCH)
    client.flush()
    return statistics.median(timings) / 1000


for fn in SCENARIOS.values():
    for _ in range(200):
        fn()

results = {}
for name, fn in SCENARIOS.items():
    gc.collect()
    results[name] = measure(fn)

print(json.dumps(results))

Type of change

• Bug fix
• New feature
• Breaking change
• Refactor
• Documentation update
• Tooling, CI, or repo maintenance

Verification

uv run --frozen ruff check .                                # All checks passed!
uv run --frozen ruff format --check .                      # 575 files already formatted
uv run --frozen mypy langfuse --no-error-summary            # no errors
uv run --frozen pytest -n auto --dist worksteal tests/unit  # 922 passed, 2 skipped

New test: test_metadata_budget_is_exact_at_the_limit pins the metadata budget at the exact limit. It includes overwrites and reserved keys that are already on the span or in the same write. An early return that is too loose by one fails it (checked by loosening the bound to max_attributes + 1), and no existing test catches that.

Not run: tests/e2e and tests/live_provider, which need a server and provider keys. This change has no network behavior.

Checklist

• I self-reviewed the diff using code_review.md.
• I added or updated tests for behavior changes.
• I updated docs, examples, or .env.template if needed. (n/a, internal-only change)
• I did not hand-edit generated files; if generated files changed, I used the upstream regeneration path.
• I did not commit secrets or credentials.

  

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ DavidTraina
❌ cursoragent
_{You have signed the CLA already but the status is still pending? Let us recheck it.}