Add trace IDs, spans, metadata, guardrails, and versioned prompt templates to Portkey requests for observability

Documented steps

1. Ensure requests already go through Portkey via the SDK or the x-portkey-* headers before layering observability on.
2. Generate a trace_id per logical user request or workflow. This is the only required field for basic tracing and can be any string you choose, such as your own request UUID.
3. Pass it via the SDK or headers. Python: portkey.with_options(trace_id='1729', span_id='11', span_name='LLM Call').chat.completions.create(...). You can also set trace_id, span_id, and span_name on the Portkey(...) constructor. Node: pass { traceId: '1729', spanId: '11', spanName: 'LLM Call' } as the second requestOptions argument to chat.completions.create.
4. On raw HTTP, use the headers directly: x-portkey-trace-id, x-portkey-span-id, x-portkey-span-name.
5. For multi-step or agentic flows, give each step a unique span_id and a descriptive span_name, and link child spans to their parent so the trace renders as a tree. Spans without a parent become root nodes.
6. If you already emit W3C tracing, Portkey accepts traceparent (version-trace_id-parent_id-trace_flags) and baggage (userId=alice,environment=production). When only traceparent is supplied, Portkey generates a gateway span id and names the span after the HTTP method and path.
7. Attach structured context with x-portkey-metadata as a JSON object, for example {"_user": "user_123", "environment": "prod"}. These keys become dashboard filters and are also what conditional routing queries against.
8. Create guardrail checks in the Portkey Guardrails product, then reference their IDs in a Config using the simplified fields: "input_guardrails": ["guardrails-id-xxx"] and "output_guardrails": ["guardrails-id-yyy"].
9. The legacy hook-based form achieves the same result and remains supported: "before_request_hooks": [{"id": "guardrail-id-xx"}] and "after_request_hooks": [{"id": "guardrail-id-yy"}]. Input guardrails run before the LLM call; output guardrails run after the response.
10. Attach the guardrails-enabled Config the same way as any other Config: SDK config: 'pc-***' or the x-portkey-config header.
11. For blocking behavior, run the guardrail synchronously (async=false) and inspect the hook_results object in the response, which carries verdicts, individual check outcomes, timings, and feedback metadata, before acting on the model output.
12. Build reusable prompts in the Prompt Engineering Studio UI under Prompts > Create. It supports 20+ providers, model parameters (top_p, max_tokens, logit_bias), JSON mode, and tool/function chains.
13. Use Mustache templating in the prompt body: {{variable}} to insert, {{#variable}}...{{/variable}} for conditionals and loops, {{^variable}}...{{/variable}} for negation, {{>partial-name}} for partials, {{! comment }} for comments.
14. Call the deployed prompt from code instead of hardcoding text: portkey.prompts.completions.create({ promptID: 'pp-hr-bot-5c8c6e', variables: { ... } }).
15. Click Update to save a new template version, then Publish to deploy it to production traffic.
16. Combine metadata with conditional routing (for example route on metadata.user_plan) so the same fields drive both observability and routing decisions.