feat(otel): cap default exporter batches at 64 MiB

[hassiebp]

What does this PR do?

Brings the JS SDK's export batch byte cap (langfuse-js#928) to Python. It uses the upstream OTLP/HTTP exporter's max_request_size (open-telemetry/opentelemetry-python#5369), first released in OpenTelemetry Python 1.45.0.

• The OpenTelemetry minimum is raised to >=1.45.0,<2 for opentelemetry-api, opentelemetry-sdk and opentelemetry-exporter-otlp-proto-http. Every install therefore drops any serialized export request over 64 MiB (measured before compression) before it is sent. The drop is reported as a failed export, and the warning contains only the sizes.
• LANGFUSE_OTEL_MAX_BATCH_SIZE_BYTES (a positive integer, same name and rules as JS) overrides the limit on the default exporter. Invalid values log a warning and keep 64 MiB.
• The check runs after masking and media processing, because Langfuse's transforming exporter wraps the OTLP exporter.
• Custom span_exporters are untouched, and flush_at is unchanged.

Other changes needed for OpenTelemetry 1.45

• Lockfile guard: the repo keeps its global exclude-newer = "7 days". Only the OpenTelemetry packages that move together get a 3 days exemption via exclude-newer-package, so the lockfile can resolve 1.45.0 / 0.66b0. The exemption does nothing once 1.45 is older than 7 days and can be deleted then.
• AttributeValue alias: 1.45 redefines opentelemetry.util.types.AttributeValue as the recursive AnyValue, which mypy rejects as a type alias. langfuse.types.AttributeValue now keeps the previous shape, so the public mask-function types are unchanged.
• Header tests: the 1.45 exporter stores headers on exporter._client and lowercases their names. test_additional_headers_simple.py is updated to match.

Behavior notes for release notes

• Batches over 64 MiB are no longer sent.
• Installing this release requires OpenTelemetry 1.45 or newer. Environments that pin an older OTel or semantic-conventions version will hit a resolver conflict.
• OTel 1.45 changes the exporter's default HTTP transport from requests.Session to urllib3, which does not read HTTPS_PROXY or REQUESTS_CA_BUNDLE. This PR deliberately leaves that alone.

Type of change

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

Verification

uv lock --check                                   # also with CI's uv 0.11.2
uv run --frozen ruff check .                      # All checks passed!
uv run --frozen ruff format --check langfuse tests/unit/test_span_processor.py tests/unit/test_additional_headers_simple.py
uv run --frozen mypy langfuse --no-error-summary
uv run --frozen pytest -n auto --dist worksteal tests/unit -q   # 709 passed, 2 skipped
uv run --frozen --python 3.10 --isolated pytest tests/unit/test_span_processor.py tests/unit/test_additional_headers_simple.py tests/unit/test_mask_otel_spans.py   # 73 passed

The new tests in tests/unit/test_span_processor.py go through the real exporter to a local HTTP server:

• Boundary: a limit of 1 byte below the request size drops it and nothing is sent; a limit exactly at or above the size sends it.
• Batched flush: an oversized batch is dropped on flush, the warning does not contain span content, and a later small batch is still delivered.
• Defaults and bad values: the limit is 64 MiB when the env var is unset, and invalid values fall back to it.

I checked that these tests fail when the env var is not passed to the exporter.

End-to-end through Langfuse() on the locked environment with LANGFUSE_OTEL_MAX_BATCH_SIZE_BYTES=5000:

opentelemetry.exporter.otlp.proto.http.trace_exporter WARNING Dropping span batch: serialized size 20463 bytes exceeds max_request_size 5000 bytes.
opentelemetry-exporter-otlp-proto-http 1.45.0
after oversized batch -> requests received: []
after small batch     -> requests received: [455]

Not run: tests/e2e and tests/live_provider, which need a Langfuse server and provider credentials. CI runs them. ruff format --check . also flags tests/unit/test_media.py, which already fails on main and is not touched here.

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.
• 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: 4/5

The PR should address the client-initialization failure for oversized numeric configuration before merging.

Summary

The PR adds an environment-configurable serialized request-size limit for the SDK-created OTLP exporter, using signature detection to retain compatibility with older OpenTelemetry versions.

• Custom exporters remain unchanged.
• Invalid numeric configuration needs more robust handling at client initialization.

_{Reviews (1) · Last reviewed commit: "feat(otel): cap oversized export batches..."}

[github-actions]

@claude review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-30T09:38:14.854244Z	636ce19	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude Code Review

No review was started: this request came from a bot account. Manual reviews can only be requested by someone with write access to this repository. Ask a maintainer to comment @claude review, or have your automation post the comment from a user account with write access.

_{Tip: disable this comment in your organization's Code Review settings.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f8635204c3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 24a44ff1dd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 636ce19420

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".