Expose OpenTelemetry SpanKind in manual span APIs

[ayaangazali]

This adds the optional kind from #171 to the manual span APIs. span(), startSpan() and startPendingSpan() accept kind?: SpanKind through a dedicated SpanOptions type that extends LogOptions, so the log helpers keep their existing options and can't pick up a kind. instrument() takes the same option via InstrumentOptions. The kind is forwarded to Tracer.startSpan() / startActiveSpan(), the manual pending placeholder in startPendingSpanWithSettings reuses it, and PendingSpanProcessor already copies span.kind onto automatic placeholders, so pending and final spans stay consistent on both paths. Omitting kind still produces INTERNAL spans.

Fixes #171

Tests: new spanKind.integration.test.ts with an in-memory exporter covering CLIENT/SERVER/PRODUCER/CONSUMER across both span() call shapes, startSpan(), startPendingSpan() (placeholder and real span get the same kind), instrument(), and the INTERNAL default. Docs example added to docs/reference/api.md, changeset included (minor for logfire). Ran pnpm run check from the root (build, vp check, typecheck, all package tests, release tooling), all green on Node 24.

quick note: I built this with Claude Code's help and reviewed the final diff myself. apologies if I missed something obvious, freshman in college trying my best to contribute, would genuinely love feedback :)

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 10f58af3-14b5-4289-b9e3-f4c419882c18

📥 Commits

Reviewing files that changed from the base of the PR and between 11a0832 and eaab4e9.

📒 Files selected for processing (5)

• docs/reference/api.md
• packages/logfire-api/src/__test__/collectSpans.ts
• packages/logfire-api/src/index.ts
• packages/logfire-api/src/spanKind.integration.test.ts
• packages/logfire-api/src/startPendingSpan.integration.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• pydantic/logfire (manual)
• pydantic/pydantic-ai (manual)

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/reference/api.md
• packages/logfire-api/src/index.ts

---

📝 Walkthrough

Walkthrough

Manual span APIs now accept an optional OpenTelemetry SpanKind and forward it during span creation. The option is supported by span(), startSpan(), startPendingSpan(), and instrument(), with pending placeholders matching their real spans and omitted values remaining INTERNAL. Integration tests verify exported kinds and defaults, while documentation and a changeset describe the API behavior.

Possibly related PRs

• pydantic/logfire-js#173: Directly overlaps with the SpanKind option propagation and pending-span testing changes.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding OpenTelemetry SpanKind support to manual span APIs.
Description check	✅ Passed	The description directly describes the SpanKind API updates, tests, docs, and fix.
Linked Issues check	✅ Passed	The PR implements the linked issue goals: kind forwarding, pending-span preservation, defaults, tests, and docs.
Out of Scope Changes check	✅ Passed	The changes stay within SpanKind support, test harness cleanup, docs, and related regression handling.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[petyosi]

There is one runtime contract issue to address before merging in packages/logfire-api/src/index.ts:442: startSpanWithSettings() now forwards options.kind unconditionally, while logWithSettings() calls it with { ...options, log: true }. A JavaScript caller—or fully typed TypeScript using const options: SpanOptions = { kind: SpanKind.CLIENT }—can therefore pass that object to info() and export a CLIENT log instead of an INTERNAL one. This contradicts the new documentation and changes the previous behavior, where the extra property was ignored. Please only forward kind when resolvedOptions.log !== true (or strip it on the log path), and add a regression test showing log helpers remain INTERNAL when a runtime options object contains kind. The intended manual span APIs and documentation otherwise look good.

[ayaangazali]

good catch, you're right that the spread through logWithSettings let a runtime kind leak into logs. fixed in 9bf8f66: startSpanWithSettings now drops kind when resolvedOptions.log === true, plus a regression test where a SpanOptions-typed object with kind: CLIENT goes through info() and the exported span stays ['log', INTERNAL]. pnpm run check green.

[ayaangazali]

ready for another look whenever you get a chance: the kind-leak into logs is fixed in 9bf8f66 with a regression test, full check green.