fix: conform feature_flag span event to the OTEL spec

[Vadman97]

Summary

Brings the feature_flag span event into conformance with the OTEL spec (OTEL v1.0.0, ACCEPTED).

Three requirements were unmet:

Req	Spec says	This hook did
1.2.2.11	feature_flag.result.variationIndex is an int	emitted str(...)
1.2.2.10	feature_flag.result.reason.inExperiment is a boolean	emitted the string 'true'
1.2.2.9 / 1.2.4	support feature_flag.set.id and a configurable environmentId	not implemented

The Go tracing hook (go-server-sdk/ldotel) already emits the specified types and supports set.id, so this also removes a cross-SDK inconsistency.

Why the types matter

Consumers matching on the typed value silently never matched. Our own OTel documentation gives this collector filter:

- 'not ((name == "feature_flag" and attributes["feature_flag.result.reason.inExperiment"] == true) or name == "exception")'

== true does not match the string "true", so that documented example did not work against spans produced by this hook.

Changes

• variationIndex → int, inExperiment → True
• New HookOptions.environment_id; when set, emits feature_flag.set.id (req 1.2.2.9.1.1)
• Invalid environment_id (non-string or empty) is ignored and logged to the ldclient.otel logger, equivalent to unset (reqs 1.2.4.1, 1.2.4.2)
• attributes annotated Dict[str, AttributeValue] so mypy accepts the mixed value types
• 7 new tests, including an explicit type-contract test to stop the strings regressing

Not implemented: req 1.2.2.9.2

Sourcing the environment ID from EvaluationSeriesContext when it is not configured is not implementable today. launchdarkly-server-sdk 9.14.1 exposes no environment ID on either EvaluationSeriesContext (key / context / default_value / method only) or plugin EnvironmentMetadata (sdk / sdk_key / application). Go has seriesContext.EnvironmentID(); Python has no equivalent. Only the config path (1.2.2.9.1) is covered here.

Compatibility

This changes the wire type of two attributes. Anyone filtering on the string forms ("true", "0") in a downstream OTel backend will need to match the typed values instead.

No impact on LaunchDarkly Observability data. Ingest stringifies span event attributes via fmt.Sprintf("%v", v) (backend/clickhouse/trace_row.go attributesToMap) into String columns, so True → "true" and 0 → "0" — byte-identical to the previous output.

Testing

• make test — 19 passed (12 pre-existing, 7 new)
• make lint — mypy, isort, pycodestyle all clean

Note for reviewers

Spec req 1.2.3.3 looks internally inconsistent and I did not touch it: it says the variation span must carry feature_flag.context.key, but its own prose cross-references 1.2.2.5, which defines feature_flag.context.id. Both this hook and the Go hook set context.id. Separately, the public observability docs state that a flag span event is identified by carrying feature_flag.context.key. Worth reconciling, but that's a spec decision rather than a code fix.

🤖 Generated with Claude Code

---

Note

Overview
Brings feature_flag span events into OTEL spec conformance by fixing attribute types and adding optional environment ID support.

variationIndex is now emitted as an int (was a string), and inExperiment as a boolean (was 'true'). Downstream filters matching on typed values will now work; filters that matched the old string forms need updating.

Adds optional HookOptions.environment_id, which emits feature_flag.set.id when set to a non-empty string. Invalid values are ignored with a warning on the ldclient.otel logger.

^{Reviewed by Cursor Bugbot for commit 4060136. Bugbot is set up for automated code reviews on this repo. Configure here.}

[kinyoklion]

This needs the update for reading the environment ID from the stream headers. The ability to configure it is a fallback.

The hook should include the environment ID. If the go SDK is currently only doing this, then it needs updated as well and I can check that.

Example of setting it from the .Net SDK: https://github.com/launchdarkly/dotnet-core/blob/98cf36ab260906284bc5276b8c656c399925d14e/pkgs/telemetry/src/TracingHook.cs#L235

Python has the eventsource embedded, so it should be a very small change really.