fix(langchain): coerce LangGraph str-subclass node ids to str for OTel attributes (#4447)

[linhongyu510]

Summary

Closes #4447.

LangGraph permits StrEnum (and other str-subclass) node ids. extract_graph_structure appended them raw to the nodes list, which is then passed to span.set_attribute(gen_ai.workflow.nodes, ...). OpenTelemetry validates sequence attributes with an exact-type check (type(element) in (bool, str, bytes, int, float)), so a str subclass is rejected — the entire gen_ai.workflow.nodes attribute is dropped and opentelemetry.attributes logs a warning on every graph invocation.

Fix

Coerce node ids to a plain str when collecting them in langgraph_utils.extract_graph_structure. Edges are unaffected because they are already built via f-strings (which produce exact-str instances).

nodes.append(str(node_id))  # was: nodes.append(node_id)

Verification

End-to-end with a real LangGraph graph using StrEnum node ids and a recording TracerProvider:

• Before: WARNING opentelemetry.attributes: Invalid type NodeName in attribute 'gen_ai.workflow.nodes' value sequence → the attribute is None (dropped).
• After: gen_ai.workflow.nodes == ("parse", "classify"), no warning.

Added tests/test_langgraph_graph_structure.py (3 self-contained tests, no API/VCR): str-subclass coercion, the OTel attribute being accepted end-to-end, and unchanged behavior for plain-string ids. The two str-subclass tests fail on the unpatched code (KeyError: 'gen_ai.workflow.nodes' / non-str element types) and pass with the fix.

Summary by CodeRabbit

• Bug Fixes

  • Improved LangGraph workflow tracing compatibility by ensuring graph node identifiers are recorded as standard text values.
  • Prevented OpenTelemetry attribute rejection when workflows use specialized string-based node identifiers.

• Tests

  • Added coverage for specialized and standard node identifiers.
  • Verified that workflow nodes and edges remain correctly represented and accepted by OpenTelemetry.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 0c6b1d9e-2eba-406f-ba46-99c46c4c60ae

📥 Commits

Reviewing files that changed from the base of the PR and between 62e24c2 and 2bcd855.

📒 Files selected for processing (2)

• packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/langgraph_utils.py
• packages/opentelemetry-instrumentation-langchain/tests/test_langgraph_graph_structure.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

LangGraph graph extraction now converts node IDs to exact str values. Tests cover StrEnum IDs, special-node filtering, OpenTelemetry attribute validation, and existing plain-string behavior.

Changes

LangGraph node ID normalization

Layer / File(s)	Summary
Normalize extracted node IDs packages/opentelemetry-instrumentation-langchain/.../langgraph_utils.py, packages/opentelemetry-instrumentation-langchain/tests/test_langgraph_graph_structure.py	extract_graph_structure converts node IDs to plain strings. Test fixtures model compiled graphs and graph edges.
Validate graph attributes packages/opentelemetry-instrumentation-langchain/tests/test_langgraph_graph_structure.py	Tests verify StrEnum conversion, special-node exclusion, OpenTelemetry acceptance, and unchanged plain-string behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 2bcd8

The change narrowly converts LangGraph node IDs to plain strings so OpenTelemetry accepts the workflow node attribute, with focused tests covering the affected behavior. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the LangChain fix and the conversion of LangGraph str-subclass node IDs for OpenTelemetry attributes.
Linked Issues check	✅ Passed	The change satisfies issue #4447 by coercing LangGraph node IDs to plain str values before recording gen_ai.workflow.nodes. The added tests cover StrEnum IDs, OpenTelemetry attribute acceptance, and e…
Out of Scope Changes check	✅ Passed	The production change and supporting tests are directly related to issue #4447. No unrelated code changes are described.

Full details: Linked Issues check

Explanation

The change satisfies issue #4447 by coercing LangGraph node IDs to plain str values before recording gen_ai.workflow.nodes. The added tests cover StrEnum IDs, OpenTelemetry attribute acceptance, and existing plain-string behavior.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}