📚 Where to Find the OpenAI Request ID in Weave Traces

docs/debugging/where-to-find-the-openai-request-id-in-weave-traces.md

@@ -0,0 +1,119 @@
+# Where to Find the OpenAI Request ID in Weave Traces
+
+## Overview
+
+This guide explains where you would expect to find the OpenAI request ID when inspecting Weave traces, and clarifies the current limitations and assumptions based on the available information.
+
+## Prerequisites
+
+- Access to the Weave tracing interface (web UI or equivalent).
+- An application that:
+  - Uses the OpenAI API, and  
+  - Is instrumented with Weave to capture traces of OpenAI calls.
+- Basic familiarity with:
+  - OpenAI API responses and logging.
+  - Weave decorators or middleware used for tracing.
+
+## Explanation
+
+Based on the discussion:
+
+- OpenAI support often requires **request IDs** to help debug issues.
+- OpenAI request IDs are typically available in **standard OpenAI logging** and/or in the **OpenAI API response metadata**.
+- The OpenAI call itself **appears in the Weave trace**, but:
+  - There is **no confirmed field** in the current Weave trace that explicitly exposes the OpenAI request ID.
+  - A team member indicated they would need to **add the request ID to Weave decorators** to make it visible in traces.
+
+In other words:
+
+1. **Today (as described):**
+   - You can see that an OpenAI call occurred in Weave.
+   - The **exact OpenAI request ID may not be visible** in the Weave trace by default.
+
+2. **Intended/expected behavior:**
+   - The OpenAI request ID should be available via:
+     - Standard OpenAI logging in your application, and/or
+     - A custom Weave decorator that extracts the request ID from the OpenAI response and attaches it to the trace.
+
+## Suggested Steps (Until Decorators Are Updated)
+
+Because the current behavior is not fully implemented or confirmed, use the following approach:
+
+1. **Check your application logs**
+   - Look for logs around the time of the OpenAI call.
+   - If you log the full OpenAI response or metadata, the request ID is often found in:
+     - A field such as `response.id`, or
+     - A header such as `x-request-id` (depending on the client and logging setup).
+
+2. **Correlate logs with Weave traces**
+   - Use timestamps, user IDs, or other contextual information to match:
+     - A specific Weave trace of an OpenAI call, with
+     - The corresponding application log entry that contains the OpenAI request ID.
+
+3. **Add or update a Weave decorator (if you control the code)**
+   - Modify your OpenAI call wrapper or Weave decorator to:
+     - Extract the request ID from the OpenAI response.
+     - Attach it as a field/attribute on the Weave span/trace (for example, `openai_request_id`).
+   - After deployment, verify in Weave that:
+     - Each OpenAI call span includes the `openai_request_id` (or similar) field.
+
+## Important Notes and Caveats
+
+- **No confirmed field in Weave yet:**  
+  The Slack discussion explicitly states:  
+  > “There are none in Weave. Let me see if I can add it to our Weave decorators.”  
+  This implies that, at the time of that conversation, **the request ID was not yet surfaced in Weave**.
+
+- **Relying on standard OpenAI logging:**  
+  Another participant noted:  
+  > “I’m like 90% that it’s in the standard OpenAI logging, not something special.”  
+  This suggests that the request ID is available via **OpenAI’s normal response/logging mechanisms**, but not automatically integrated into Weave.
+
+- **Uncertainty / possible misremembering:**  
+  One participant acknowledged:  
+  > “but obv I could be misremembering”  
+  This means the exact location and availability of the request ID in Weave is **not definitively confirmed**.
+
+- **No specific Weave UI path or field name provided:**  
+  The conversation does not specify:
+  - Which tab, panel, or field in the Weave UI would show the request ID.
+  - Any concrete JSON path or attribute name in the trace payload.
+
+## Troubleshooting Tips
+
+If you cannot find the OpenAI request ID in Weave:
+
+1. **Verify that OpenAI responses are logged**
+   - Ensure your application logs include either:
+     - The full OpenAI response object, or
+     - At least the request ID field from the response or headers.
+
+2. **Inspect raw trace data (if available)**
+   - If Weave allows viewing raw span/trace JSON:
+     - Search for fields like `id`, `request_id`, `openai_request_id`, or similar.
+     - If none exist, the request ID is not currently being captured.
+
+3. **Confirm decorator or middleware behavior**
+   - Check your Weave integration code:
+     - Does it intercept the OpenAI response?
+     - Does it explicitly attach the request ID to the trace?
+   - If not, you will need to implement this.
+
+4. **Coordinate with your team**
+   - Ask the team member who mentioned “add it to our Weave decorators”:
+     - Whether that change has been implemented.
+     - What field name is used for the request ID in Weave.
+     - From which version or deployment it is available.
+
+5. **Information still needed**
+   To provide a precise, step-by-step location in the Weave UI, you would need:
+   - The **exact field name** used for the OpenAI request ID in the trace.
+   - The **Weave UI navigation path** (e.g., “Open the trace → select the OpenAI span → look under ‘Attributes’ → field `openai_request_id`”).
+   - Confirmation of whether the decorator change has been deployed in your environment.
+
+Until that information is confirmed, the reliable approach is to:
+- Use **application logs** to obtain the OpenAI request ID, and
+- Correlate those logs with Weave traces using timestamps and contextual metadata.
+
+---
+*Source: [Original Slack thread](https://distylai.slack.com/archives/impl-tower-streaming/p1752004706645579)*