Add SSE fan-out tracing span and propagate correlation/trace id into emitted SSE events

[Jagadeeshftw]

📌 Description

src/tracing/hooks.ts provides traceDbQuery, traceRedisCommand, traceStellarRpc, and traceWebhookDispatch, but no helper traces SSE fan-out. Meanwhile src/streams/sseEmitter.ts carries a correlationId on the update event but does not propagate trace context into the emitted SSE frames, so the trace chain breaks at the SSE boundary. Add a traceSseDispatch() helper and include the correlation/trace id in the SSE event so consumers can correlate.

💡 Why it matters: SSE delivery is currently a tracing blind spot, breaking end-to-end request correlation.

🧩 Requirements and context

• Add traceSseDispatch() to src/tracing/hooks.ts wrapping the fan-out with subscriber-count and stream-id attributes.
• Include the correlation/trace id as a field/comment line in emitted SSE frames in src/streams/sseEmitter.ts.
• Keep cardinality bounded (no per-subscriber spans by default).
• Ensure the span closes even when a subscriber write throws.
• Document the SSE trace-propagation contract.

Non-functional requirements

• Must be secure, tested, and documented.
• Should be efficient and easy to review.

🛠️ Suggested execution

1. Fork the repo and create a branch

git checkout -b sse-tracing

2. Implement changes

• Write/modify the relevant source: src/tracing/hooks.ts, src/streams/sseEmitter.ts
• Write comprehensive tests: tests/tracing/hooks.test.ts, tests/routes/streams-sse.test.ts
• Add documentation: inline TSDoc + README tracing section
• Include TSDoc doc comments on traceSseDispatch
• Validate security assumptions: trace ids exposed to clients are non-sensitive

3. Test and commit

• Run tests:

npm test

• Cover edge cases: subscriber write error, zero subscribers, span closure
• Include test output and security notes in the PR description.

Example commit message

feat(tracing): add SSE fan-out span and propagate correlation id into SSE events

✅ Acceptance criteria

• traceSseDispatch() exists and is used in the emitter
• SSE frames carry the correlation/trace id
• Span includes subscriber-count and stream-id attributes
• Span closes on subscriber write error
• Trace-propagation contract documented

🔒 Security notes

Only expose non-sensitive correlation/trace identifiers in client-visible SSE frames; never embed internal tokens.

📋 Guidelines

• Minimum 95% test coverage
• Clear documentation
• Timeframe: 96 hours

[1sgtpepper]

Hi, I’d like to work on this.

This is a focused tracing issue because SSE fan-out currently breaks the request-to-client observability chain. I have TypeScript backend and tracing/streaming experience, plus bug bounty experience with several contest placements.

Plan: add an SSE dispatch tracing helper, wrap fan-out without per-subscriber cardinality, propagate the correlation id in SSE frames, document the contract, and add tests for fan-out and error handling.

[malik203]

@malik203 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I’m interested in contributing to meaningful projects, solving problems, and writing clean, efficient code.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @malik203 to this issue.

[wavyboy-build]

@wavyboy-build has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Let me work on this issue, i deliver fast

ℹ️ Repo Maintainers: To accept this application, review their application or assign @wavyboy-build to this issue.

[drips-wave]

Congratulations, @malik203! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @malik203: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊