Merge pull request #562 from future-agi/fix/rewrite-tracing-mask-span

rewrite manual tracing mask span

Author: hadarishav

src/pages/docs/observe/features/manual-tracing/mask-span-attributes.mdx

@@ -1,26 +1,28 @@
 ---
 title: "Mask Span Attributes"
-description: "Redact sensitive inputs, outputs, images, and embeddings from spans before they are exported — using environment variables or TraceConfig in code."
+description: "Redact sensitive inputs, outputs, images, and embeddings from spans before they are exported:using environment variables or TraceConfig in code."
 ---
 
-## What it is
+## About
 
-**Mask Span Attributes** lets you control which data gets recorded in your traces. Using environment variables or a `TraceConfig` object passed to any auto-instrumentor, you can hide inputs, outputs, messages, images, text, and embedding vectors before they leave your application. This is useful for preventing sensitive data from being logged and for reducing payload size when working with large base64-encoded images.
+Traces often contain sensitive data: user messages, API responses, PII, or large base64-encoded images. Sending all of this to a trace backend creates privacy, compliance, and payload size problems. Masking span attributes removes or truncates this data before it leaves the application. Configuration is available at two levels: environment variables for global defaults across all instrumentors, and `TraceConfig` in code for per-instrumentor control.
 
-## Use cases
+---
+
+## When to use
 
-- **Privacy and compliance** — Hide user inputs and LLM outputs to prevent sensitive data from being stored in trace backends.
-- **Image redaction** — Suppress base64-encoded images from input messages or cap their length to reduce payload size.
-- **Selective masking** — Hide only specific parts of a span (e.g. input text but not output messages) while keeping the rest visible.
-- **Environment-specific config** — Use environment variables for deployment-level defaults and `TraceConfig` in code for per-instrumentor overrides.
+- **Privacy and compliance**: Hide user inputs and LLM outputs to prevent sensitive data from being stored in trace backends.
+- **Image redaction**: Suppress base64-encoded images from input messages or cap their length to reduce payload size.
+- **Selective masking**: Hide only specific parts of a span (e.g. input text but not output messages) while keeping the rest visible.
+- **Environment-specific config**: Use environment variables for deployment-level defaults and `TraceConfig` in code for per-instrumentor overrides.
 
 ---
 
 ## How to
 
-<Steps>
-  <Step title="Review available settings">
-    The following environment variables control what gets masked. Set them before your application starts for a global default, or configure them in code using `TraceConfig` (see next step).
+<Tabs>
+  <Tab title="Environment Variables">
+    These apply globally to all instrumentors at startup.
 
     | Environment Variable | Description | Type | Default |
     |----------------------|-------------|------|---------|
@@ -33,10 +35,10 @@ description: "Redact sensitive inputs, outputs, images, and embeddings from span
     | `FI_HIDE_OUTPUT_TEXT` | Hides text from output messages | bool | False |
     | `FI_HIDE_EMBEDDING_VECTORS` | Hides returned embedding vectors | bool | False |
     | `FI_BASE64_IMAGE_MAX_LENGTH` | Caps the character count of a base64 encoded image | int | 32,000 |
-  </Step>
+  </Tab>
 
-  <Step title="Configure in code with TraceConfig">
-    Pass a `TraceConfig` object to any auto-instrumentor to set masking options directly in code. Values set here take precedence over environment variables.
+  <Tab title="TraceConfig in Code">
+    Pass a `TraceConfig` object to any auto-instrumentor for per-instrumentor control. Values set here take precedence over environment variables.
 
     <CodeGroup>
 
@@ -63,47 +65,40 @@ description: "Redact sensitive inputs, outputs, images, and embeddings from span
     ```
 
     ```javascript JS/TS
-    import { OpenAIInstrumentor, FITraceConfig } from "@traceai/openai";
-    import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-
-    const config: FITraceConfig = {
-        hideInputs: false,
-        hideOutputs: false,
-        hideInputMessages: false,
-        hideOutputMessages: false,
-        hideInputImages: false,
-        hideInputText: false,
-        hideOutputText: false,
-        hideEmbeddingVectors: false,
-        base64ImageMaxLength: 32000,
-    };
-
-    const instrumentor = new OpenAIInstrumentor();
-    instrumentor.instrument(
-        tracerProvider,
-        config
-    );
-
-    console.log("OpenAIInstrumentor configured with custom TraceConfig.");
+    const { OpenAIInstrumentation } = require("@traceai/openai");
+
+    const instrumentation = new OpenAIInstrumentation({
+        traceConfig: {
+            hideInputs: false,
+            hideOutputs: false,
+            hideInputMessages: false,
+            hideOutputMessages: false,
+            hideInputImages: false,
+            hideInputText: false,
+            hideOutputText: false,
+            hideEmbeddingVectors: false,
+            base64ImageMaxLength: 32000,
+        },
+    });
     ```
 
     </CodeGroup>
-  </Step>
-</Steps>
+  </Tab>
+</Tabs>
 
 ---
 
 ## Key concepts
 
-- **`TraceConfig`** — An object accepted by all traceAI auto-instrumentors. Use it to specify masking settings directly in code, scoped to a single instrumentor.
-- **Environment variables** — Global defaults applied to all instrumentors. Useful for deployment-level configuration without changing code.
-- **Precedence order** — `TraceConfig` in code → environment variables → default values. More specific settings always win.
-- **`hide_inputs` / `hide_outputs`** — Broad flags that hide all input/output values and messages in one setting.
-- **`base64_image_max_length`** — Caps the logged length of base64-encoded images. Default is 32,000 characters.
+- **`TraceConfig`**:An object accepted by all traceAI auto-instrumentors. Use it to specify masking settings directly in code, scoped to a single instrumentor.
+- **Environment variables**:Global defaults applied to all instrumentors. Useful for deployment-level configuration without changing code.
+- **Precedence order**:`TraceConfig` in code → environment variables → default values. More specific settings always win.
+- **`hide_inputs` / `hide_outputs`**:Broad flags that hide all input/output values and messages in one setting.
+- **`base64_image_max_length`**:Caps the logged length of base64-encoded images. Default is 32,000 characters.
 
 ---
 
-## What you can do next
+## Next Steps
 
 <CardGroup cols={2}>
   <Card title="Set Up Tracing" icon="gear" href="/docs/observe/features/manual-tracing/set-up-tracing">