From 3d01f33ccb7dd1ff63356516beddb370ada71128 Mon Sep 17 00:00:00 2001 From: Sam Brenner Date: Tue, 21 Oct 2025 10:44:31 -0400 Subject: [PATCH 1/6] add annotationContext docs for llmobs node.js --- .../llm_observability/instrumentation/sdk.md | 74 ++++++++++++++++++- 1 file changed, 72 insertions(+), 2 deletions(-) diff --git a/content/en/llm_observability/instrumentation/sdk.md b/content/en/llm_observability/instrumentation/sdk.md index 8eacb204a7466..407e2a878f0cf 100644 --- a/content/en/llm_observability/instrumentation/sdk.md +++ b/content/en/llm_observability/instrumentation/sdk.md @@ -1230,7 +1230,7 @@ public class MyJavaClass { LLMObsSpan taskSpan = LLMObs.startTaskSpan("preprocessDocument", null, "session-141"); ... // preprocess document for data extraction taskSpan.annotateIO(...); // record the input and output - taskSpan.finish(); + taskSpan.finish(); } public String extractData(String document) { @@ -1740,7 +1740,7 @@ public class MyJavaClass { {{< tabs >}} {{% tab "Python" %}} -The SDK's `LLMObs.annotate_context()` method returns a context manager that can be used to modify all auto-instrumented spans started while the annotation context is active. +The SDK's `LLMObs.annotation_context()` method returns a context manager that can be used to modify all auto-instrumented spans started while the annotation context is active. The `LLMObs.annotation_context()` method accepts the following arguments: @@ -1790,6 +1790,50 @@ def rag_workflow(user_question): [1]: /getting_started/tagging/ +{{% /tab %}} + +{{% tab "Node.js" %}} + +The SDK's `llmobs.annotationContext()` accepts a callback function that can be used to modify all auto-instrumented spans started while inside the scope of the callback function. + +The `llmobs.annotationContext()` method accepts the following options on the first argument: + +{{% collapse-content title="Arguments" level="h4" expanded=false id="annotating-autoinstrumented-span-arguments" %}} + +`name` +: optional - _str_ +
Name that overrides the span name for any auto-instrumented spans that are started within the annotation context. + +`tags` +: optional - _dictionary_ +
A dictionary of JSON serializable key-value pairs that users can add as tags on the span. Example keys: `session`, `env`, `system`, and `version`. For more information about tags, see [Getting Started with Tags][1]. + +{{% /collapse-content %}} + +#### Example + +{{< code-block lang="javascript" >}} +const { llmobs } = require('dd-trace'); + +@workflow +function ragWorkflow(userQuestion) { + const contextStr = retrieveDocuments(userQuestion).join(" "); + + const completion = await llmobs.annotationContext({ + tags: { + retrieval_strategy: "semantic_similarity" + }, + name: "augmented_generation" + }, async () => { + const completion = await openai_client.chat.completions.create(...); + return completion.choices[0].message.content; + }); +} + +{{< /code-block >}} + +[1]: /getting_started/tagging/ + {{% /tab %}} {{< /tabs >}} @@ -2161,6 +2205,32 @@ function redactProcessor(span) { llmobs.registerProcessor(redactProcessor) {{< /code-block >}} +### Example: conditional modification with auto-instrumentation + +When using auto instrumentation, the span is not always contextually accessible. To conditionally modify the inputs and outputs on auto-instrumented spans, `llmobs.annotationContext()` can be used in addition to a span processor. + +{{< code-block lang="javascript" >}} +const { llmobs } = require('dd-trace'); + +function redactProcessor(span) { + if (span.getTag("no_input") == "true") { + for (const message of span.input) { + message.content = "" + } + } + + return span +} + +llmobs.registerProcessor(redactProcessor) + +function callOpenai() { + llmobs.annotationContext({ tags: { no_input: "true" } }, async () => { + // make call to openai + }) +} +{{< /code-block >}} + ### Example: preventing spans from being emitted {{< code-block lang="javascript" >}} From 6e62b5d21bce7e211ef8c2abeac5adcb68a98aed Mon Sep 17 00:00:00 2001 From: Sam Brenner Date: Tue, 21 Oct 2025 11:05:50 -0400 Subject: [PATCH 2/6] fixups --- content/en/llm_observability/instrumentation/sdk.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/content/en/llm_observability/instrumentation/sdk.md b/content/en/llm_observability/instrumentation/sdk.md index 407e2a878f0cf..5a900496ce768 100644 --- a/content/en/llm_observability/instrumentation/sdk.md +++ b/content/en/llm_observability/instrumentation/sdk.md @@ -1815,7 +1815,6 @@ The `llmobs.annotationContext()` method accepts the following options on the fir {{< code-block lang="javascript" >}} const { llmobs } = require('dd-trace'); -@workflow function ragWorkflow(userQuestion) { const contextStr = retrieveDocuments(userQuestion).join(" "); @@ -2215,19 +2214,19 @@ const { llmobs } = require('dd-trace'); function redactProcessor(span) { if (span.getTag("no_input") == "true") { for (const message of span.input) { - message.content = "" + message.content = ""; } } return span } -llmobs.registerProcessor(redactProcessor) +llmobs.registerProcessor(redactProcessor); -function callOpenai() { - llmobs.annotationContext({ tags: { no_input: "true" } }, async () => { +async function callOpenai() { + await llmobs.annotationContext({ tags: { no_input: "true" } }, async () => { // make call to openai - }) + }); } {{< /code-block >}} From e87e32611396a359fb35deee1ad34015d14c60e5 Mon Sep 17 00:00:00 2001 From: Sam Brenner Date: Tue, 21 Oct 2025 12:28:30 -0400 Subject: [PATCH 3/6] change collapsible header name --- content/en/llm_observability/instrumentation/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/llm_observability/instrumentation/sdk.md b/content/en/llm_observability/instrumentation/sdk.md index 5a900496ce768..553b292aa9f62 100644 --- a/content/en/llm_observability/instrumentation/sdk.md +++ b/content/en/llm_observability/instrumentation/sdk.md @@ -1798,7 +1798,7 @@ The SDK's `llmobs.annotationContext()` accepts a callback function that can be u The `llmobs.annotationContext()` method accepts the following options on the first argument: -{{% collapse-content title="Arguments" level="h4" expanded=false id="annotating-autoinstrumented-span-arguments" %}} +{{% collapse-content title="Options" level="h4" expanded=false id="annotating-autoinstrumented-span-arguments" %}} `name` : optional - _str_ From 7d3b37e346d448c48b6ead519be8810bf465f934 Mon Sep 17 00:00:00 2001 From: Sam Brenner Date: Wed, 22 Oct 2025 09:24:57 -0400 Subject: [PATCH 4/6] change "dictionary" to "object" for node.js --- content/en/llm_observability/instrumentation/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/llm_observability/instrumentation/sdk.md b/content/en/llm_observability/instrumentation/sdk.md index 553b292aa9f62..a49394e61f818 100644 --- a/content/en/llm_observability/instrumentation/sdk.md +++ b/content/en/llm_observability/instrumentation/sdk.md @@ -1805,8 +1805,8 @@ The `llmobs.annotationContext()` method accepts the following options on the fir
Name that overrides the span name for any auto-instrumented spans that are started within the annotation context. `tags` -: optional - _dictionary_ -
A dictionary of JSON serializable key-value pairs that users can add as tags on the span. Example keys: `session`, `env`, `system`, and `version`. For more information about tags, see [Getting Started with Tags][1]. +: optional - _object_ +
An object of JSON serializable key-value pairs that users can add as tags on the span. Example keys: `session`, `env`, `system`, and `version`. For more information about tags, see [Getting Started with Tags][1]. {{% /collapse-content %}} From 8c21d1fc4c7c1b55f70b189d7f6156b4d214be60 Mon Sep 17 00:00:00 2001 From: Sam Brenner <106700075+sabrenner@users.noreply.github.com> Date: Wed, 22 Oct 2025 09:37:35 -0400 Subject: [PATCH 5/6] Update content/en/llm_observability/instrumentation/sdk.md Co-authored-by: kyle --- content/en/llm_observability/instrumentation/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/llm_observability/instrumentation/sdk.md b/content/en/llm_observability/instrumentation/sdk.md index a49394e61f818..57ca1f3c019c9 100644 --- a/content/en/llm_observability/instrumentation/sdk.md +++ b/content/en/llm_observability/instrumentation/sdk.md @@ -2218,7 +2218,7 @@ function redactProcessor(span) { } } - return span + return span; } llmobs.registerProcessor(redactProcessor); From eac4a752fec0b6e68afe70c2b8633436ff999685 Mon Sep 17 00:00:00 2001 From: Sam Brenner Date: Wed, 22 Oct 2025 12:58:34 -0400 Subject: [PATCH 6/6] fix for getting started with tagging link --- content/en/llm_observability/instrumentation/sdk.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/content/en/llm_observability/instrumentation/sdk.md b/content/en/llm_observability/instrumentation/sdk.md index a49394e61f818..54b4bd307a8c4 100644 --- a/content/en/llm_observability/instrumentation/sdk.md +++ b/content/en/llm_observability/instrumentation/sdk.md @@ -1756,7 +1756,7 @@ The `LLMObs.annotation_context()` method accepts the following arguments: `tags` : optional - _dictionary_ -
A dictionary of JSON serializable key-value pairs that users can add as tags on the span. Example keys: `session`, `env`, `system`, and `version`. For more information about tags, see [Getting Started with Tags][1]. +
A dictionary of JSON serializable key-value pairs that users can add as tags on the span. Example keys: `session`, `env`, `system`, and `version`. For more information about tags, see [Getting Started with Tags](/getting_started/tagging/). {{% /collapse-content %}} @@ -1788,8 +1788,6 @@ def rag_workflow(user_question): {{< /code-block >}} -[1]: /getting_started/tagging/ - {{% /tab %}} {{% tab "Node.js" %}} @@ -1806,7 +1804,7 @@ The `llmobs.annotationContext()` method accepts the following options on the fir `tags` : optional - _object_ -
An object of JSON serializable key-value pairs that users can add as tags on the span. Example keys: `session`, `env`, `system`, and `version`. For more information about tags, see [Getting Started with Tags][1]. +
An object of JSON serializable key-value pairs that users can add as tags on the span. Example keys: `session`, `env`, `system`, and `version`. For more information about tags, see [Getting Started with Tags](/getting_started/tagging/). {{% /collapse-content %}} @@ -1831,8 +1829,6 @@ function ragWorkflow(userQuestion) { {{< /code-block >}} -[1]: /getting_started/tagging/ - {{% /tab %}} {{< /tabs >}}