Skip to content

feat(python): add set_attributes and custom span/log processors - #859

Merged
abelonogov-ld merged 2 commits into
mainfrom
andrey/global-attributes-python
Nov 3, 2026
Merged

abelonogov-ld merged 2 commits into
mainfrom
andrey/global-attributes-python

Conversation

@abelonogov-ld

@abelonogov-ld abelonogov-ld commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds global attributes and custom span/log processors to the Python observability plugin. This is one of a set of matching PRs across RN, Android, iOS, Flutter, MAUI, Java and Python that share the same semantics.

Global attributes

  • observe.set_attributes(mapping) and observe.remove_attributes(keys) maintain one in-memory, thread-safe attribute map for the whole process (lock + read-only snapshot rebuilt on change). Safe to call before init.
  • Applied to every span (manual, instrumented and exception spans; values are taken when the span starts), every log record (including stdlib logging through the SDK handler), and every metric recorded through observe.record_*.
  • Precedence: per-call attributes > globals > resource. Globals only fill missing keys, and only into remaining attribute-limit capacity, so explicit attributes are never evicted.

Custom processors (init-time options)

  • ObservabilityConfig(span_processors=[...], log_processors=[...]) (opentelemetry.sdk.trace.SpanProcessor, opentelemetry.sdk._logs.LogRecordProcessor).
  • Pipeline: global attributes, then user processors in order, then the SDK's batch exporters, so user changes are exported.
  • Exceptions from user processors are logged and never stop export; force_flush / shutdown are forwarded.

Also: OTel's base SpanProcessor.force_flush returns None, which TracerProvider treats as a failed flush and stops before the exporting processor. The global-attributes processor returns True, and the user-processor wrapper only treats an explicit False as failure, so explicit flushes still reach the exporter.

Note: value validation reuses OTel's opentelemetry.attributes._clean_attribute (private) so globals follow exactly the same rules as span attributes.

How did you test this change?

  • 35 new pytest tests (110 total) with in-memory span, log and metric exporters: merge/remove, read-only snapshots, invalid values, concurrent writers, set-before-init, per-call precedence on spans/logs/metrics, start-time capture, instrumented and exception spans, stdlib logging, processor order with changes exported, raising processors, flush/shutdown forwarding, and the real _OTELConfiguration wiring with network mocked.
  • make lint, make test and poetry build pass.

Are there any deployment considerations?

None. Both features are opt-in and additive; without set_attributes or the new options, behaviour is unchanged.


Note

Overview
Adds process-wide global telemetry attributes and configurable OpenTelemetry processors to the Python observability SDK, with matching e2e coverage in the Flask sample app.

Global attributes: New observe.set_attributes / observe.remove_attributes maintain a thread-safe in-memory map (immutable snapshots) that can be set before plugin init. Globals are merged onto spans at start (via GlobalAttributesSpanProcessor), log records (including stdlib logging), and all observe.record_* metrics. Per-call attributes win over globals; globals only fill missing keys and respect OTel attribute limits.

Custom processors: ObservabilityConfig now accepts span_processors and log_processors. Wiring runs global attributes → user processors (exception-safe wrappers) → batch exporters, with fixes so force_flush still reaches exporters when user processors return None.

Docs and the Flask e2e app document a UTM-style repro (repro.py) that asserts expected attributes on manual span, log, and metric routes. A large new test_global_attributes.py suite covers precedence, concurrency, processor ordering, and export survival on processor errors.

Reviewed by Cursor Bugbot for commit 9201b50. Bugbot is set up for automated code reviews on this repo. Configure here.

Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines Covered Coverage Threshold Status
2280 2098 92% 0% 🟢

New Files

File Coverage Status
sdk/@launchdarkly/observability-python/ldobserve/_otel/global_attributes.py 96% 🟢
sdk/@launchdarkly/observability-python/ldobserve/_otel/processors.py 100% 🟢
sdk/@launchdarkly/observability-python/ldobserve/test_global_attributes.py 99% 🟢
TOTAL 98% 🟢

Modified Files

File Coverage Status
sdk/@launchdarkly/observability-python/ldobserve/_otel/configuration.py 87% 🟢
sdk/@launchdarkly/observability-python/ldobserve/config.py 99% 🟢
sdk/@launchdarkly/observability-python/ldobserve/observe.py 81% 🟢
sdk/@launchdarkly/observability-python/ldobserve/test_observe_instance.py 99% 🟢
TOTAL 91% 🟢

updated for commit: 9201b50 by action🐍

Co-authored-by: Cursor <cursoragent@cursor.com>
abelonogov-ld added a commit that referenced this pull request Nov 3, 2026
## Summary

Adds global attributes and custom span/log processors to the Java server
observability plugin. This is one of a set of matching PRs across RN,
Android, iOS, Flutter, MAUI, Java and Python that share the same
semantics (see #858, #859, #860,
launchdarkly/swift-launchdarkly-observability#290).

**Global attributes**
- `LDObserve.setAttributes(Attributes)` /
`LDObserve.removeAttributes(Collection<String>)` keep one process-wide
attribute set (`AtomicReference` to an immutable snapshot). Safe before
init and thread-safe.
- Applied to every span the plugin's tracer provider starts (manual
spans, flag evaluations, error spans, and instrumentation wired to
`LDObserve.getOpenTelemetry()`), every log record, and metrics recorded
through `LDObserve`.
- Precedence: per-call / span-builder values > globals > resource.
Globals only fill missing keys (matched by name, regardless of type);
spans get the values current at start.
- Globals survive `LDObserve.shutdown()` (process-wide lifetime).

**Custom processors** (init-time options)
- `ObservabilityOptions.Builder.spanProcessors(List<SpanProcessor>)` /
`logProcessors(List<LogRecordProcessor>)`, plus `spanProcessor(...)` /
`logProcessor(...)` to add one at a time (mirrors `customHeaders` /
`customHeader`).
- Order: global attributes → user processors (in order) → the plugin's
level filter, sampling and batch export, so user changes are exported
and sampling still applies.
- Each user call is wrapped in try/catch: a throwing processor is logged
(WARNING once, then FINE) and export continues; `forceFlush` /
`shutdown` are forwarded and return a failed result instead of
propagating.

**Dependency change:** `opentelemetry-sdk` moves from `implementation`
to `api` (compile scope in the published POM), because
`ObservabilityOptions` now exposes SDK processor types.
`checkPublishedPom` enforces this. Same version; it was already a
transitive runtime dependency.

Not covered: metrics recorded on a meter obtained via
`getOpenTelemetry()` (only `LDObserve` metric methods merge globals);
documented in the README.

## How did you test this change?

- `./gradlew :lib:build` (javadoc, POM, classpath and fixture checks,
tests) and `./gradlew :lib:test -PldServerSdkVersion=7.10.1` (as CI)
pass: 146 tests, 0 failures.
- Unit tests (`GlobalAttributesTest`, `SafeProcessorTest`):
merge/remove, name matching across types, per-call precedence,
null/empty input, concurrent writes, span and log filling, throwing
processors, flush/shutdown forwarding.
- End-to-end `PluginUserFlowTest` with a real `LDClient` and a local
OTLP collector: globals set before start reach flag-evaluation, manual
and error spans, logs and metrics; per-call values win; removed keys are
not applied; spans keep start-time values; user processors run in order
and their changes reach the exported payload; sampling still drops
matching spans; throwing processors don't break export, flush or
shutdown.
- A mutation check (removing the wrapping and the global-attributes
processor) makes the new end-to-end tests fail.
- `javap` confirms every SDK method used exists in OpenTelemetry 1.38.0,
the plugin's minimum.

## Are there any deployment considerations?

- The published POM lists `opentelemetry-sdk` at compile scope instead
of runtime scope; consumers see SDK types on their compile classpath.
- Purely additive API; no behavior change unless these APIs are used.
- Processors are read when the providers start; a second `LDClient` with
a different SDK key doesn't add its processors, consistent with how its
other options are already ignored.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> Adds **process-wide global attributes** and **user-defined
OpenTelemetry processors** to the Java observability plugin, aligned
with other LaunchDarkly SDKs.
> 
> **Global attributes:** New `LDObserve.setAttributes` /
`removeAttributes` keep a thread-safe, merge-by-key store (safe before
plugin init, survives shutdown). Globals are applied to exported spans
and logs via dedicated processors in `OtelManager`, and to metrics
recorded through `LDObserve` via `GlobalAttributes.merge`. Per-call or
span-builder attributes win on key conflicts; spans snapshot globals at
start.
> 
> **Custom processors:** `ObservabilityOptions` now accepts ordered
`SpanProcessor` and `LogRecordProcessor` lists (single-add helpers too).
They run after global-attribute injection and before level filtering,
sampling, and export; failures are wrapped in `SafeSpanProcessor` /
`SafeLogRecordProcessor` so export continues.
> 
> **Packaging:** `opentelemetry-sdk` is promoted to compile-scoped `api`
because processor types are part of the public options API; POM checks
were updated.
> 
> The Spring Boot e2e app sets UTM globals before startup and prints
`[#1]` expectations on each request so manual verification in
LaunchDarkly is straightforward.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
be24b27. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
@abelonogov-ld
abelonogov-ld merged commit 3f04a85 into main Nov 3, 2026
25 checks passed
@abelonogov-ld
abelonogov-ld deleted the andrey/global-attributes-python branch November 3, 2026 23:56
abelonogov-ld added a commit that referenced this pull request Nov 6, 2026
## Summary

Adds a global attributes API to the Android observability SDK. This is
one of a set of matching PRs across SDKs that share the same semantics
(see #858, #859, #861, #856, #863,
launchdarkly/swift-launchdarkly-observability#290).

- `LDObserve.setAttributes(Attributes)` and
`LDObserve.setAttributes(Map<String, Any?>)` merge attributes by key
into one in-memory, process-wide map;
`LDObserve.removeAttributes(Collection<String>)` removes keys.
- Applied to every span (values captured at span start), every log
record (including crash reports) and every metric data point recorded
after the call, including the launch-time histogram.
- Precedence: per-call attributes > globals > resource. Globals only
fill missing keys and never overwrite. Upstream
`OtelRumConfig.setGlobalAttributes` is intentionally not used, because
its appenders overwrite per-call values. Instead, internal span and log
processors are registered ahead of the SDK's sampling and export
processors, and metric record methods merge globals under per-call
values.
- `session.id` and `highlight.session_id` are ignored (a warning is
logged).
- Not persisted and not cleared on session rotation. Calls made before
the SDK initializes take effect, because the store exists independently
of the SDK instance.
- Reads are a lock-free load of an immutable snapshot; writes rebuild it
under a lock.
- README documents the API with a Kotlin example.

## How did you test this change?

- New JVM unit tests (`GlobalAttributesStoreTest`,
`GlobalAttributesPipelineTest`): merge/remove, re-setting a key with a
different value type, reserved keys, per-call precedence, concurrent
writers, set-before-init through `LDObserve`, globals captured at span
start, and globals reaching exported spans, logs and metric data points
through real OpenTelemetry providers wired like the SDK.
- `./gradlew :lib:compileDebugKotlin :lib:test` passes (559 tests, debug
and release).

## Are there any deployment considerations?

- `ObservabilityOptions` is unchanged. The only API change is three new
methods on `Observe` (inherited by `LDObserve` and its companion), with
default implementations, so Kotlin implementers need no changes.
- Java and MAUI callers use `LDObserve.Companion.setAttributes(...)` /
`removeAttributes(...)`, like the other `LDObserve` methods. #863 (MAUI)
is stacked on this PR.
- Global attributes are added to metric data points, so they increase
metric cardinality.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> Adds **process-wide global attributes** on the Android observability
SDK via `LDObserve.setAttributes` (OTel `Attributes` or plain map) and
`LDObserve.removeAttributes`.
> 
> Globals are stored in a singleton **`GlobalAttributesStore`** so calls
**before SDK init** still apply once the pipeline starts. They are
merged into **spans** (snapshot at span start), **logs** (via new
processors registered ahead of sampling/export), and **metrics**
(including launch-time histograms), with **per-call attributes winning**
over globals and reserved session keys ignored with a warning. README
and the compose e2e app document/repro UTM-style globals and precedence.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
7e24d72. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
vadim-korolik pushed a commit that referenced this pull request Nov 6, 2026
🤖 I have created a release *beep* *boop*
---


<details><summary>launchdarkly-observability-python: 1.4.0</summary>

##
[1.4.0](launchdarkly-observability-python-1.3.4...launchdarkly-observability-python-1.4.0)
(2026-11-06)


### Features

* **python:** add set_attributes and custom span/log processors
([#859](#859))
([3f04a85](3f04a85))
</details>

<details><summary>launchdarkly-observability-android: 0.70.0</summary>

##
[0.70.0](launchdarkly-observability-android-0.69.1...launchdarkly-observability-android-0.70.0)
(2026-11-06)


### Features

* **android:** add setAttributes and removeAttributes
([#860](#860))
([a1c02b2](a1c02b2))
</details>

<details><summary>launchdarkly-java-server-sdk-observability:
0.2.0</summary>

##
[0.2.0](launchdarkly-java-server-sdk-observability-0.1.0...launchdarkly-java-server-sdk-observability-0.2.0)
(2026-11-06)


### Features

* **java:** add setAttributes and custom span/log processors
([#861](#861))
([d0ee65e](d0ee65e))
</details>

<details><summary>o11y: 1.6.0</summary>

##
[1.6.0](o11y-1.5.0...o11y-1.6.0)
(2026-11-06)


### Features

* **o11y:** capture UTM query parameters and landing referrer as
attributes
([#877](#877))
([f32637b](f32637b))


### Bug Fixes

* **o11y:** report @launchdarkly/o11y as telemetry.distro.name
([#879](#879))
([7f339e1](7f339e1))
</details>

<details><summary>observability: 1.5.0</summary>

##
[1.5.0](observability-1.4.0...observability-1.5.0)
(2026-11-06)


### Features

* **o11y:** capture UTM query parameters and landing referrer as
attributes
([#877](#877))
([f32637b](f32637b))


### Dependencies

* The following workspace dependencies were updated
  * dependencies
    * @launchdarkly/o11y bumped to 1.6.0
</details>

<details><summary>observability-next: 0.3.6</summary>

##
[0.3.6](observability-next-0.3.5...observability-next-0.3.6)
(2026-11-06)


### Dependencies

* The following workspace dependencies were updated
  * dependencies
    * @launchdarkly/observability bumped to 1.5.0
    * @launchdarkly/session-replay bumped to 1.2.6
</details>

<details><summary>session-replay: 1.2.6</summary>

##
[1.2.6](session-replay-1.2.5...session-replay-1.2.6)
(2026-11-06)


### Dependencies

* The following workspace dependencies were updated
  * dependencies
    * @launchdarkly/o11y bumped to 1.6.0
</details>

<details><summary>highlight.run: 10.8.6</summary>

##
[10.8.6](highlight.run-10.8.5...highlight.run-10.8.6)
(2026-11-06)


### Dependencies

* The following workspace dependencies were updated
  * dependencies
    * @launchdarkly/o11y bumped to 1.6.0
</details>

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> **Release automation** updates `.release-please-manifest.json` and
every consumer manifest to cut `@launchdarkly/o11y` **1.6.0**,
`@launchdarkly/observability` **1.5.0**, `@launchdarkly/session-replay`
**1.2.6**, `highlight.run` **10.8.6**,
`@launchdarkly/observability-next` **0.3.6**, Android **0.70.0**, Java
**0.2.0**, and Python **1.4.0** while regenerating their CHANGELOG
notes.
> 
> **Packaging metadata** bumps Gradle `version` tokens
(`sdk/@launchdarkly/observability-android/gradle.properties`,
`sdk/@launchdarkly/observability-java/gradle.properties`) and
`INSTRUMENTATION_VERSION` so published telemetry reports the new Java
plugin revision, refreshes `pyproject.toml`/`PROVENANCE.md` for the
Python wheel, and keeps `@launchdarkly/observability-java`’s constants
aligned.
> 
> **Doc churn** extends each touched SDK changelog with the
corresponding feature or dependency bullets (e.g., marketing UTM capture
for browser o11y, attribute helpers on Android/Java/Python, workspace
dependency bumps for Next/session-replay/highlight packages).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
18ddf54. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants