feat(tracing): allow explicit observation start times

[ShellWen]

What does this PR do?

Adds an optional nanosecond start_time to manual root and child observations. This makes manual observation creation symmetric with end(end_time=...) and preserves historical durations when an integration emits spans after the underlying work has completed

Fixes #1377

Type of change

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

Verification

uv run --frozen pytest -q tests/unit/test_otel.py
uv run --frozen mypy langfuse --no-error-summary
uv run --frozen ruff check .
uv run --frozen ruff format --check .

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.

Greptile Summary

This PR adds explicit start times for manually created observations. The main changes are:

• Adds an optional nanosecond start_time to root and child observation APIs.
• Passes explicit start times to OpenTelemetry span creation.
• Uses explicit timestamps for manually created child events.
• Tests historical start and end times for root and generation spans.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.
• Existing behavior remains unchanged when start_time is omitted.
• Explicit timestamps are forwarded on both root creation paths and the child observation path.

_{Reviews (1): Last reviewed commit: "feat(tracing): allow explicit observatio..." | Re-trigger Greptile}

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Adds support for explicitly setting observation start timestamps (nanoseconds since epoch) when manually creating root and child observations, enabling accurate historical durations for delayed span emission workflows (e.g., replaying OpenTelemetry spans from stored exports).

Changes:

• Extend start_observation(...) (client + child observations) to accept an optional start_time: Optional[int] and forward it to the underlying OpenTelemetry tracer.
• Ensure event-type child observations can use an explicit start_time (otherwise defaulting to time_ns()).
• Add a unit test asserting that provided historical start_time values are preserved on exported spans.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
langfuse/_client/client.py	Adds start_time to root observation creation and forwards it to _otel_tracer.start_span(...).
langfuse/_client/span.py	Adds start_time to child observation creation (including event handling) and forwards it to _otel_tracer.start_span(...).
tests/unit/test_otel.py	Adds coverage verifying historical start/end timestamps are preserved for manual root + child observations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.