zoriya/drizzle-otel
1
0
Fork 0
mirror of https://github.com/zoriya/drizzle-otel.git synced 2025-12-06 00:46:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
Alex Holovach
2025-10-07 10:26:02 -05:00
parent 339238280c
commit 4f731b4949
1 changed files with 0 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
packages/otel-upstash-queues/README.md
View File

@@ -291,78 +291,6 @@ async function handler(request: Request) {
export const POST = verifySignatureAppRouter(instrumentConsumer(handler));
```
## How It Works
### Publisher Instrumentation
The `instrumentUpstash` function creates OpenTelemetry spans for publishing by:
1. Wrapping the `publishJSON` method of the QStash client
2. Creating a CLIENT span before the operation starts
3. Adding relevant attributes from the request parameters
4. Capturing the message ID from the response
5. Recording any errors that occur
6. Properly closing the span with success or error status
### Consumer Instrumentation
The `instrumentConsumer` function creates OpenTelemetry spans for receiving by:
1. Wrapping your message handler function
2. Creating a SERVER span when a message is received
3. Extracting QStash headers (message ID, retry count, etc.)
4. Executing your handler within the span context
5. Capturing the HTTP response status code
6. Recording any errors during processing
7. Properly closing the span with success or error status
All of this happens automatically once you wrap your client and handlers with the instrumentation functions.
## Best Practices
### Publisher Best Practices
1. **Instrument Early**: Call `instrumentUpstash()` when you create your QStash client, typically at application startup.
2. **Reuse the Client**: Create one instrumented client and reuse it throughout your application.
3. **Use Deduplication IDs**: For idempotent operations, always provide a `deduplicationId` to prevent duplicate processing.
4. **Set Appropriate Retries**: Configure retry counts based on the criticality and nature of your tasks.
### Consumer Best Practices
1. **Instrument Before Verification**: Always wrap your handler with `instrumentConsumer()` before wrapping with `verifySignatureAppRouter()`:
```ts
export const POST = verifySignatureAppRouter(instrumentConsumer(handler));
```
2. **Return Proper Status Codes**: Ensure your handler returns appropriate HTTP status codes. Non-2xx status codes will mark the span as an error.
3. **Handle Errors Gracefully**: Let errors bubble up naturally - the instrumentation will capture them and mark the span appropriately.
4. **Monitor Retry Patterns**: Use the `qstash.retried` attribute to track retry patterns and identify problematic messages.
### Configuration Best Practices
1. **Body Capture in Development**: Enable `captureBody` in development environments for easier debugging:
```ts
const config = {
captureBody: process.env.NODE_ENV === "development",
maxBodyLength: 2048,
};
```
2. **Protect Sensitive Data**: Be cautious about enabling body capture in production if your messages contain sensitive information (PII, credentials, etc.).
3. **Set Appropriate Limits**: Use `maxBodyLength` to prevent excessively large spans. Bodies exceeding this limit will be truncated with `"... (truncated)"` appended.
### General Best Practices
1. **Monitor Traces**: Use OpenTelemetry-compatible tracing backends (like Jaeger, Zipkin, or cloud providers) to visualize your message queues.
2. **Correlate Publisher and Consumer**: The `qstash.message_id` attribute allows you to correlate publisher and consumer spans for end-to-end tracing.
## License
MIT