fix(client.spans): improve error messages for missing fields

[sahusiddharth]

Resolves: #9500

This PR enhances the client.spans.log_spans error handling to provide clearer and more actionable feedback when span creation fails.

• Enhanced missing field validation to explicitly list the missing required keys (e.g., "Missing required keys in Span: ['status_code']").
• Included test cases covering Non-existent project identifiers and Spans missing required fields (such as status_code).

Use this notebook for quick replication: https://colab.research.google.com/drive/1cA7c3aVZrzx_-inVrNewebqqJFF1Hghi?usp=sharing

---

Note

Raise SpanCreationError with a descriptive message on 404 project lookups and emit explicit missing-key details in validation errors; add/update integration tests.

• Client (spans):
  • log_spans: on 404 now raises SpanCreationError with "Project not found" guidance instead of generic HTTP error.
  • Validation parsing (_extract_invalid_span_from_log_spans_error):
    • Detects "missing" errors and reports explicit missing required keys (e.g., ['status_code']), accounting for Python ≤3.10 vs ≥3.11 (Span.__required_keys__).
  • Minor: import sys to check version_info.
• Tests (tests/integration/client/test_spans.py):
  • Update non-existent project case to expect SpanCreationError with "Project not found".
  • Add test asserting missing required fields error lists the absent keys and span identifiers.

^{Written by Cursor Bugbot for commit e758d39. This will update automatically on new commits. Configure here.}

[cursor]

Bug: Span Type Missing Required Keys Attribute

The _extract_invalid_span_from_log_spans_error function attempts to use Span.__required_keys__ on Python 3.11+ to provide specific error messages for missing span fields. However, Span is an alias for a generated type (v1.Span) that may not expose this attribute, causing an AttributeError at runtime and preventing helpful error messages.

 

[sahusiddharth]

Hi @anticorrelator,

whenever you get a chance, could you please take a look at this PR and let me know if any changes are needed?

[sahusiddharth]

I had a couple of follow-up questions regarding this issue and the recent fix:

1. Client-side validation before sending spans:
   Would it make sense to perform basic validation on the client side (e.g., checking for all required span fields) before sending the HTTP request? Instead of collecting errors from it from the response.

2. Use of Pydantic for schema validation:
   Using Pydantic could make schema validation simpler and more maintainable, especially for span structures that closely follow a fixed schema, why TypedDict?

Would love to hear your thoughts on these

[anticorrelator]

Instead of two strategies that depends on the Python version let's just use one

[sahusiddharth]

Hi @anticorrelator,

I added the version-specific logic because SpanDataType inherits from TypedDict, and the NotRequired marker is ignored at runtime in Python ≤3.10, meaning all keys are treated as required in those versions. From 3.11 onwards, we can correctly extract required keys via required_keys.

That’s why I went with the version-dependent approach as a fallback. But I’m happy to explore a cleaner or more consistent strategy if you have any suggestions

I’d love to learn a better way to handle this.

[anticorrelator]

Thanks for the contribution! We don't need to warn on non-existent projects anymore and we should probably use a different strategy for letting users know about missing fields on Spans

[sahusiddharth]

Hi @anticorrelator

One possible approach could be to define a constant (e.g. DEFAULT_REQUIRED_KEYS) and use that instead of the version check. The only trade-off is that we’d need to manually keep that list in sync if the required fields ever change.

Would you prefer that I move ahead with this approach, or would you recommend another direction here? Just wanted to confirm before making the change.