A support agent has just been slow, costly, and wrong. Yet the conventional dashboard is reassuring: every API request returned 200, p95 latency is below the service SLO, and there is no unhandled exception. One log line says tool=get_customer_profile; another says retry=1. None of that explains the incident. Did the agent select the wrong tool? Did it retry after an upstream failure? Which prompt revision produced the route? How many tokens did the retry consume? Did the trace exporter retain the authorization header that arrived inside a tool error?

The predictable response is to capture everything: the system prompt, user messages, retrieved chunks, tool arguments, tool results, completions, and perhaps model reasoning when a framework exposes it. That can make one investigation convenient while quietly creating a second data lake—one filled with customer conversations, credentials, PII, payment context, and internal payloads, but without the mature contracts, retention limits, reviews, and access controls of the primary systems of record.

The core principle: a trace is an execution record, not a conversation transcript. Preserve enough evidence to explain the agent’s path, cost, authority, and policy decisions. Route raw content through a separate, explicit, short-lived, access-controlled path.

This is not an argument for shallow observability. Tool-calling agents need more visibility than conventional request/response services: they branch, retrieve, retry, call models, invoke tools, and sometimes change the outside world. OpenTelemetry’s GenAI conventions provide useful vocabulary for model identity, token counts, duration, tool calls, and—only when explicitly enabled—content. The fact that content capture is off by default matters: observability is not the same thing as permission to collect text.

This article builds a practical production design for tracing prompts, tool calls, tokens, and cost without converting logs into a data-exposure surface. The running example is RelayDesk, a multi-tenant customer-support agent that searches a knowledge base, reads account state, creates refund drafts, and sends email after approval. Every customer value, secret, price, and trace sample below is synthetic.

Start with incident questions, not a vendor schema

Before choosing a tracing SDK or a backend, write down the questions an on-call engineer should answer in the first ten minutes of an incident. A field that cannot answer one of those questions should not enter default telemetry.

The question design prevents a dangerous premise: that reading raw content is the only way to debug. It frequently is not. If tool.get_customer_profile is slow, retries three times because of UPSTREAM_429, and has a restricted output class, you already have a disciplined investigation path without seeing an address, a card number, or a bearer token.

NIST frames post-deployment AI monitoring as more than infrastructure availability. It includes functionality, operations, human factors, security, and compliance. Its recent review also identifies fragmented logging, degradation detection, and balancing automated with human-validated monitoring as recurring challenges. An agent dashboard that only shows latency is therefore an incomplete operating model.

Separate four telemetry planes instead of stuffing everything into span attributes

A defensible design separates evidence by the question it serves, the people who may read it, and its retention policy. A single giant span JSON gives you the worst of both worlds: too little structure for operations and too much content to protect.

OpenTelemetry’s own sensitive-data guidance makes the responsibility clear: instrumentation cannot know what is sensitive in a specific business context. Implementers need to review emitted data, apply data minimization, collect only what serves an observability purpose, and consider aggregation or anonymization where possible. “Turn on auto-instrumentation and inspect it later” is not a production data architecture.

Use spans to preserve execution shape, not to carry payloads

For RelayDesk, an agent root span could carry a compact evidence envelope:

agent.name                  = relaydesk.support
agent.version               = 2026.08.13.3
agent.route                 = account_issue
agent.policy.version        = privacy-v7
session.correlation_id      = hmac:9f2b…
trace.content.mode          = metadata_only
agent.final.outcome_class   = refund_draft_created

A model child span can include the deployment, template revision, token usage, finish reason, and estimated cost. A tool span can include tool name, capability class, schema revision, argument shape, result class, duration, retries, and effect. None of those fields requires a customer name, an entire prompt, or a raw JSON result.

OpenTelemetry’s GenAI observability walkthrough uses the same essential hierarchy: an agent/root invocation with child chat and tool-execution spans, plus attributes for model identity, tokens, and finish reasons. When content recording is enabled, full messages and tool information can be attached. That is a policy choice, not a harmless default.

A minimum trace model for a tool-calling agent

Teams commonly mix three distinct categories of information:

1. Identity and revision identify the agent, prompt template, tool schema, model deployment, and policy revision. They let you compare runs meaningfully.
2. Behavior captures routing, tool sequence, retries, guardrail decisions, and side-effect class. It establishes what the agent did.
3. Payload contains prompts, retrieved documents, tool arguments/results, and completions. It has the highest privacy and security risk and should not occupy the default path.

The following schema is intentionally vendor-neutral. The attribute prefixes can vary; the data contract should not.

A RelayDesk incident without a transcript

Assume RelayDesk receives: “I was charged twice. Check my account and issue a refund if that is correct.” It calls get_customer_profile, then lookup_billing_events, and finally creates a refund draft. The billing tool times out once and the agent retries.

A metadata-first production trace can still say this:

trace.id=7b4e…  agent.version=2026.08.13.3  tenant.tier=regulated
├─ policy.classify           8ms   class=restricted  action=redact
├─ llm.plan                 91ms  model=… input=1840 output=436 cost=$0.0048
├─ tool.get_customer_profile 68ms capability=customer.read result=found effect=read_only
├─ tool.lookup_billing       61ms capability=billing.read result=upstream_timeout retry=1
├─ tool.lookup_billing       54ms capability=billing.read result=found effect=read_only
└─ tool.create_refund_draft  39ms capability=refund.draft approval=required effect=staged

That tells the on-call engineer that the agent retried once, ended with a staged—not externally executed—action, and spent more because of an additional model/tool path. It does not reveal the customer’s billing records, street address, email, or upstream header.

A trace ID is a correlation handle. It is not a ticket that grants access to a transcript. Treating it as one collapses the boundary between normal observability and exceptional evidence access.

Classify data before capture: allow, summarize, tokenize, redact, or drop

Redaction is not the last regex in a pipeline. It is a data-contract decision that should happen before the exporter sends a span out of the process. Every prospective field should take one of five paths.

Hashing alone is not an anonymization guarantee. OpenTelemetry explicitly warns that a hash of a small or predictable input space—for example a numeric user ID—may be reversible in practice. If you need a correlation key, prefer an HMAC managed as a secret, scoped by tenant or rotation window, and still access-controlled as sensitive telemetry. Do not put an unsalted SHA-256 email hash on a broad dashboard and call the system privacy-preserving.

A metadata-first TypeScript instrumentation wrapper

The point of the wrapper below is not to redact a complete object after it exists. It constructs a safe telemetry envelope from the start. Treat it as a pattern; map field names to the SDK and semantic conventions you use.

import crypto from "node:crypto";

type DataClass = "public" | "internal" | "restricted" | "secret";
type SafeAction = "allow" | "summarize" | "tokenize" | "redact" | "drop";

type SafeField = {
  dataClass: DataClass;
  action: SafeAction;
  fingerprint?: string;
  summary?: string;
  redactedFields?: number;
};

const key = Buffer.from(process.env.TELEMETRY_HMAC_KEY!, "base64");

function fingerprint(value: string): string {
  // This is a controlled correlation key—not a claim of anonymization.
  return crypto.createHmac("sha256", key).update(value).digest("base64url").slice(0, 20);
}

function inspectForTelemetry(input: string, kind: "prompt" | "tool_result"): SafeField {
  if (/authorization:\s*bearer/i.test(input) || /(?:api[_-]?key|password)=/i.test(input)) {
    return { dataClass: "secret", action: "redact", redactedFields: 1 };
  }
  if (/\b\d{3}-\d{2}-\d{4}\b/.test(input) || /\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(input)) {
    return { dataClass: "restricted", action: "redact", redactedFields: 1 };
  }
  return {
    dataClass: "internal",
    action: "summarize",
    fingerprint: fingerprint(input),
    summary: kind === "prompt" ? "intent:account_support" : "result:customer_profile_found",
  };
}

function traceToolCall(span: { setAttribute(k: string, v: string | number | boolean): void }, req: {
  toolName: string;
  schemaVersion: string;
  capability: "read" | "draft" | "write";
  argumentsJson: string;
  resultJson: string;
  durationMs: number;
}) {
  const args = inspectForTelemetry(req.argumentsJson, "prompt");
  const result = inspectForTelemetry(req.resultJson, "tool_result");

  span.setAttribute("agent.tool.name", req.toolName);
  span.setAttribute("agent.tool.schema.version", req.schemaVersion);
  span.setAttribute("agent.tool.capability", req.capability);
  span.setAttribute("agent.tool.duration_ms", req.durationMs);
  span.setAttribute("agent.tool.arguments.action", args.action);
  span.setAttribute("agent.tool.result.action", result.action);
  span.setAttribute("agent.tool.result.class", result.summary ?? "content_redacted");
  span.setAttribute("agent.policy.redacted_fields", (args.redactedFields ?? 0) + (result.redactedFields ?? 0));

  // Deliberately absent: argumentsJson, resultJson, authorization header, raw prompt.
}

This is not a replacement for DLP or semantic PII detection. It establishes a safer default shape: a normal code path never attaches the raw payload in the first place, regardless of exporter retries, sampling decisions, or backend changes. Grafana describes the same ordering in its SDK-side secret sanitization: messages, system prompts, tool calls, and tool results are sanitized before generation data is exported; server-side guards provide a second, centralized policy layer.

Build a layered redaction pipeline because every layer has blind spots

A production design usually needs at least five checkpoints.

Do not make backend redaction your primary defense. Once a raw prompt has crossed the network, a queue, a retry buffer, or a third-party service, it may exist in several places. OpenTelemetry provides processors to modify, filter, redact, and transform telemetry, but its guidance is unambiguous: the best way to avoid collecting sensitive telemetry is not to collect it in the first place.

The following is deliberately policy pseudoconfiguration, not copy-paste Collector syntax. Its value is in being reviewable as an allowlist-first contract; validate the exact processor syntax for your Collector version before deploying.

telemetry_policy:
  trace_attributes_allowlist:
    - service.name
    - service.version
    - agent.name
    - agent.version
    - agent.route
    - agent.tool.name
    - agent.tool.capability
    - agent.tool.duration_ms
    - gen_ai.usage.input_tokens
    - gen_ai.usage.output_tokens
    - agent.cost.usd
    - agent.policy.version
    - agent.policy.redacted_fields
  delete_attribute_patterns:
    - ".*prompt.*"
    - ".*message.*"
    - ".*authorization.*"
    - ".*cookie.*"
    - ".*tool.*arguments.*"
    - ".*tool.*result.*"
  export:
    standard_trace_store: metadata_only
    restricted_evidence_store: explicit_break_glass_only

Truncation is not a privacy control

Keeping only the first thousand characters reduces volume; it does not remove sensitivity. An API key can be in the first twenty characters, and an email, name, account number, or private instruction is often at the start of a message. Regex is also incomplete by design. Grafana distinguishes high-confidence secret-pattern sanitization from evaluator/guard approaches that can identify semantically expressed PII, and it documents different coverage for inputs, outputs, streaming, and reasoning blocks.

Test the pipeline with synthetic but hostile fixtures: a fake bearer token, fake email, fake identifier, nested JSON, base64-looking text, a tool result that contains a header, and a streaming response. The test target is not “a beautiful redactor.” It is proof that the raw value cannot appear in an exporter mock, a dead-letter queue, or a standard trace store outside the intended restricted lane.

it("never exports a synthetic bearer token in standard telemetry", async () => {
  const fakeSecret = "Bearer test_only_9Qf7r2Kp";
  const span = new MemorySpan();

  traceToolCall(span, {
    toolName: "get_customer_profile",
    schemaVersion: "v4",
    capability: "read",
    argumentsJson: JSON.stringify({ accountRef: "demo-42" }),
    resultJson: JSON.stringify({ upstreamError: `Authorization: ${fakeSecret}` }),
    durationMs: 68,
  });

  const serialized = JSON.stringify(span.attributes);
  expect(serialized).not.toContain(fakeSecret);
  expect(span.attributes["agent.tool.result.action"]).toBe("redact");
  expect(span.attributes["agent.policy.redacted_fields"]).toBe(1);
});

Trace prompt provenance rather than defaulting to transcript capture

Prompt observability tends to drift to extremes. One team saves nothing and cannot reproduce a regression. Another saves every system instruction, user message, retrieved chunk, tool schema, and completion for every request.

A better approach separates prompt provenance from prompt content.

When groundedness regresses, begin with prompt revision, index revision, tokenized document references, source count, token budget, and evaluation score. If those signals are insufficient, request restricted evidence through a break-glass flow. That deliberately slower path adds friction before a privacy-sensitive act.

Treat tool calls as authority and effect, not as HTTP status

Tool calling is where agent observability must exceed ordinary API logging. HTTP 200 does not mean “safe”: an agent may call a write tool against the wrong tenant, a tool may return far too much PII, an agent may loop a read tool and create a denial-of-wallet incident, or a technically successful action may still require approval.

OWASP identifies tool abuse, excessive autonomy, data exfiltration, prompt injection, denial of wallet, and sensitive data exposure in context or logs as specific agent risks. Its baseline recommendations include least privilege, per-tool scopes, high-impact action controls, monitoring, and data classification.

A good tool span retains behavioral evidence:

agent.tool.name                 = create_refund_draft
agent.tool.capability            = draft
agent.tool.auth_scope_class      = tenant_limited
agent.tool.argument_shape        = {account_ref: tokenized, amount: bucketed}
agent.tool.result_class          = draft_created
agent.tool.effect                = staged_no_external_side_effect
agent.tool.approval_required     = true
agent.tool.approval_state        = pending
agent.tool.retry_count           = 0
agent.tool.policy_action         = allow

argument_shape is not raw JSON. It may encode keys present, types, size buckets, and handling decisions. If amount ranges matter to operational risk, bucket them; do not retain exact values by default. For an email tool, store recipient count, domain category, capability, and approval state—not the email body or recipient address in a standard span.

Measure token, latency, and cost at the span; aggregate after policy

The cost of an agent does not live in one model invocation. It accumulates through planning, fallback models, retrieval expansion, tool loops, and retries. Each model span should therefore include input/output tokens, deployment, finish reason, duration, and a price-card revision. The root span should retain the controlled aggregate.

An illustrative calculation is simple:

span_cost_usd = (input_tokens / 1_000_000 × input_price_per_million)
              + (output_tokens / 1_000_000 × output_price_per_million)

trace_cost_usd = Σ span_cost_usd + tool_metered_cost_usd

Do not hard-code price in a dashboard query. Version a price card, attach billing.price_card_version, and label cost as an estimate when provider billing, caching, or rounding semantics differ. The numbers in this article’s charts are examples, not claims about a model’s current price.

Keep three budgets separate

A cost signal does not need a user email, a raw prompt, or complete tool arguments to be useful. Route, model class, prompt revision, tool name, tenant tier, and risk tier are usually sufficient dimensions after cardinality review. LangChain similarly emphasizes that traces make token and latency attribution possible at the step level, while production scale requires sampling and retention because humans cannot read every trace.

Sampling and retention: longer retention is not better observability

Saving full payloads for one hundred percent of traffic creates both cost and blast radius. Dropping all content makes rare investigation harder. The answer is not a single global sampling percentage; it is policy driven by risk and outcome.

The retention periods are illustrative. Real values must be derived from data classification, jurisdiction, contract, threat model, and incident policy. The non-negotiable property is that every store has an owner, access path, TTL, and deletion semantics. “Our observability backend keeps data forever” is not a retention policy.

Make content debugging a break-glass audit event

Some incidents cannot be resolved from metadata. A provider may encode an unexpected error in a tool response, or an indirect prompt injection may be visible only in a document fragment. The answer is not to set CAPTURE_CONTENT=true globally and promise to turn it off later.

Use a deliberately narrow workflow instead:

1. An engineer opens an evidence request with the trace ID, the incident reason, and the minimum necessary fields.
2. A policy service evaluates incident severity, data class, tenant restrictions, and approver roles.
3. Two independent principals approve restricted or secret evidence.
4. Only a sanitized snapshot is decrypted in a dedicated viewer; download and export are blocked or separately audited.
5. The system logs requester, fields viewed, time, and operator; TTL expiry triggers verified deletion.
6. The investigation produces a safe summary and—where valuable—a synthetic regression or evaluation case.

This design feels heavier than an unrestricted trace UI because it is. It creates an auditable boundary and prevents ordinary incident response from becoming routine bulk access to customer conversations. Grafana’s redaction documentation makes the limitation visible: SDK sanitizers and server guards have different coverage, and no single layer automatically covers response content, streaming, and model-thinking blocks in the same way. Break-glass does not replace prevention; it acknowledges legitimate investigative needs without normalizing raw-content access.

Dashboards, alerts, and runbooks should name an action

A useful dashboard is not a gallery of every attribute. It tells an owner what action is appropriate.

A redaction count that suddenly falls to zero after a release can be more urgent than one hundred additional milliseconds of latency. Alert on policy evidence, not on raw payload. Safe observability must observe itself: which policy revision processed a trace, whether fields were dropped, whether an exporter bypassed the intended path, and whether restricted-evidence access is rising.

Failure modes that turn logs into a breach

A 30-day path from console logs to defensible observability

Week 1: define the telemetry contract

Inventory existing fields across SDK auto-capture, custom logs, tool middleware, proxy headers, queue payloads, and vendor exporters. For every field, record owner, purpose, data class, default action, retention, backend, and reader. Drop fields without a purpose. Then map the ten most important incident questions to safe evidence.

Week 2: instrument the hot path

Add root agent, model, retrieval, and tool spans. Capture model/revision/tokens/duration/tool effect/policy decision; default raw content to off. Add price-card revision, retry count, approval state, and safe result class. Build views for error, duration, cost, redaction, and budget decisions.

Week 3: add enforcement and adversarial tests

Implement the SDK sanitizer and Collector allowlist. Create canary fixtures and prove that synthetic secrets never appear in exported spans. Test tool errors, nested JSON, headers, streams, and auto-instrumentation. Have Security and Privacy owners review each new field class.

Week 4: operate the feedback loop

Set sampling and retention, launch the break-glass process, route policy-bypass alerts to on-call, and turn safe incident summaries into regression-evaluation fixtures. MLflow describes agent observability as a combination of tracing, evaluation, monitoring, cost/latency tracking, feedback, and governance; those are parts of one learning loop, not disconnected product features.

Production checklist before you enable content tracing

Closing thought

Mature agent observability is not “everything is searchable.” It is the ability to answer, quickly and with evidence: what the agent did, why it did it, what it cost, whether it crossed policy, and which change produced the behavior—without loading prompts, customer data, and tool payloads into an open log repository.

Start with less data and stronger structure: revisions, trace shape, token/cost, tool effect, policy action, and controlled fingerprints. Then build a truly narrow restricted-evidence lane for the minority of incidents that need exact context. If you cannot name the incident question a field exists to answer, treat that field as a potential data leak—not as unfinished observability.

References

[1] OpenTelemetry — Inside the LLM Call: GenAI Observability with OpenTelemetry

[2] OpenTelemetry — Handling sensitive data

[3] Grafana Cloud documentation — PII and secrets redaction

[4] OWASP Cheat Sheet Series — AI Agent Security Cheat Sheet

[5] NIST — Challenges to the Monitoring of Deployed AI Systems

[6] LangChain — AI Agent Observability: Tracing, Testing, and Improving Agents

[7] MLflow — AI Observability for LLMs and Agents

Một support agent vừa khiến bạn tốn tiền, trả lời chậm và đưa ra hướng dẫn sai. Khi bạn mở dashboard, mọi thứ lại xanh: API 200, p95 dưới ngưỡng, không có exception. Một log dòng thì nói tool=get_customer_profile, dòng khác nói retry=1. Bạn vẫn không biết chuyện gì đã xảy ra: agent đã chọn tool nào trước, tool có trả về lỗi gì, prompt version nào sinh ra hành vi đó, bao nhiêu token bị đốt trong lần retry, hay policy redaction có thực sự chạy.

Phản xạ tự nhiên là log tất cả. Prompt, response, tool arguments, tool results, retrieved documents, thậm chí cả “reasoning” nếu framework cho phép. Và đó là lúc observability backend biến thành một data lake thứ hai: một nơi có PII, credential, câu chuyện khách hàng, header authorization, dữ liệu tài chính và payload nội bộ—nhưng thường không có data contract, retention policy hay access review nghiêm bằng database chính.

Luận điểm chính: Một trace là bằng chứng thực thi, không phải một transcript hội thoại. Hãy lưu đủ bằng chứng để giải thích đường đi, chi phí, quyền hạn và policy của agent; còn raw content phải đi vào một làn riêng, chỉ bật khi được phê duyệt, có thời hạn và có kiểm soát truy cập.

Đây không phải lời kêu gọi “đừng quan sát agent”. Ngược lại, agent có tool call cần quan sát sâu hơn request-response truyền thống: nó có thể gọi nhiều model, đi qua retrieval, retry, branching và tác động ra thế giới bên ngoài. OpenTelemetry đã chuẩn hóa phần lớn vocabulary cần thiết—model, token input/output, duration, tool call và, khi opt-in, cả content. Việc content capture tắt mặc định là một signal kiến trúc quan trọng: visibility không đồng nghĩa với được phép thu thập nội dung.

Bài viết này đưa ra một blueprint production cho trace prompt, tool call, token và cost mà không biến log thành rò rỉ dữ liệu. Ví dụ xuyên suốt là RelayDesk, một agent CSKH đa tenant có thể tra knowledge base, đọc trạng thái tài khoản, tạo refund draft và gửi email sau approval. Mọi customer data, token, giá tiền và trace bên dưới đều là dữ liệu minh họa.

Bài toán không phải “có log hay không”, mà là “trace phải trả lời câu gì?”

Trước khi chọn vendor, SDK hay schema, hãy viết các câu hỏi mà on-call engineer phải trả lời trong mười phút đầu của incident. Nếu một field không phục vụ ít nhất một câu hỏi, field đó không nên có mặt trong telemetry mặc định.

Bảng này buộc team bỏ một giả định nguy hiểm: “biết nội dung” là cách duy nhất để debug. Nhiều incident không cần content để xác định nguyên nhân. Nếu tool.get_customer_profile có p99 4,8 giây, được retry ba lần vì UPSTREAM_429, và output đã bị policy gắn restricted, bạn đã có đủ hướng điều tra mà không cần nhìn địa chỉ hay bearer token của khách hàng.

NIST mô tả monitoring sau triển khai của AI không chỉ là operational uptime. Nó còn chạm vào functionality, human factors, security và compliance; các team trong thực tế gặp rào cản như logging phân mảnh, drift khó phát hiện và cân bằng giữa automation với human-validated monitoring. Với agent, một dashboard latency đơn thuần không giải được những lớp câu hỏi đó.

Bốn mặt phẳng telemetry: đừng nhét mọi thứ vào span attributes

Một hệ thống lành mạnh tách các loại bằng chứng theo câu hỏi, access và retention. Nếu mọi thứ bị nhét vào một span JSON, bạn sẽ hoặc không có đủ dữ liệu để vận hành, hoặc có quá nhiều dữ liệu để bảo vệ.

OpenTelemetry khuyến nghị data minimization và nhắc rõ rằng instrumentation library không thể tự biết dữ liệu nào nhạy cảm với business của bạn. Người triển khai phải review telemetry được phát ra, chỉ giữ dữ liệu có mục đích quan sát rõ ràng, và cân nhắc aggregate/anonymize thay cho attribute gốc. Vì vậy, “cài auto-instrumentation rồi xem sau” không phải production architecture.

Một nguyên tắc gọn: spans để giải thích shape, không phải để mang payload

Với RelayDesk, root span có thể mang:

agent.name                  = relaydesk.support
agent.version               = 2026.08.13.3
agent.route                 = account_issue
agent.policy.version        = privacy-v7
session.correlation_id      = hmac:9f2b…
trace.content.mode          = metadata_only
agent.final.outcome_class   = refund_draft_created

Một child LLM span có thể mang model, temperature band, prompt template version, token usage, finish reason và cost. Một tool span mang tool name, capability class, schema version, argument shape, result class, duration, retry count và effect. Không field nào ở trên cần chứa tên khách hàng, nguyên câu prompt hay JSON tool result.

Cách này vẫn cho bạn đúng hierarchy: invoke_agent → plan → retrieve_policy → get_customer_profile → draft_refund. Bài viết về GenAI telemetry của OpenTelemetry cũng minh họa đúng cấu trúc root agent span với child chat và execute-tool spans, cùng token count, model và finish reason. Khi content capture được bật, prompt/tool content có thể xuất hiện—đó phải là một quyết định policy, không phải side effect mặc định.

Trace model tối thiểu cho một tool-calling agent

Hãy phân biệt ba thứ thường bị trộn lẫn:

1. Identity và phiên bản: agent, prompt template, tool schema, model deployment, policy version. Đây là điều kiện để so sánh hai run.
2. Hành vi: route, tool sequence, retry, guardrail decision, side-effect class. Đây là điều kiện để biết agent đã làm gì.
3. Payload: prompt, retrieved documents, tool args/results, response. Đây là nội dung có rủi ro cao và không thuộc default path.

Dưới đây là schema thực dụng. Prefix có thể tùy stack; điều quan trọng là data contract và phân loại rõ ràng.

Case study: một lỗi thật sẽ trông như thế nào?

Giả sử RelayDesk nhận câu: “Tài khoản của tôi bị trừ phí hai lần. Kiểm tra và hoàn tiền nếu đúng.” Agent gọi get_customer_profile, sau đó lookup_billing_events, rồi tạo refund draft. Tool billing gặp timeout và retry.

Trace production metadata-first có thể cho thấy:

trace.id=7b4e…  agent.version=2026.08.13.3  tenant.tier=regulated
├─ policy.classify           8ms   class=restricted  action=redact
├─ llm.plan                 91ms  model=… input=1840 output=436 cost=$0.0048
├─ tool.get_customer_profile 68ms capability=customer.read result=found effect=read_only
├─ tool.lookup_billing       61ms capability=billing.read result=upstream_timeout retry=1
├─ tool.lookup_billing       54ms capability=billing.read result=found effect=read_only
└─ tool.create_refund_draft  39ms capability=refund.draft approval=required effect=staged

Bạn biết retry đã xảy ra, có một pending approval, và cost tăng vì một LLM turn cùng tool retry. Bạn không biết số thẻ, email, địa chỉ hay header upstream—và ở đa số incident vận hành, bạn không cần biết.

Điểm cần nhớ: trace.id là correlation key. Nó không phải quyền truy cập vào raw content. Khi team coi một ID là “vé xem transcript”, họ đã phá ranh giới observability và evidence vault.

Data classification trước capture: allow, summarize, hash, redact hay drop?

Redaction không phải regex cuối pipeline. Nó là một quyết định data contract thực hiện trước khi exporter gửi span ra khỏi process. Mỗi field có thể đi qua năm action khác nhau.

Một lưu ý quan trọng: hash không tự động biến dữ liệu thành anonymous. OpenTelemetry nêu rõ hash có thể bị đảo ngược trong thực tế nếu không gian input nhỏ hoặc dự đoán được, ví dụ numeric user ID. Nếu cần correlation, dùng HMAC với secret được quản lý, scope theo tenant hoặc rotation window; và vẫn xem kết quả như dữ liệu nhạy cảm dưới access policy. Đừng đưa email SHA-256 thô lên dashboard rồi gọi đó là privacy.

Metadata-first wrapper trong TypeScript

Mục tiêu của wrapper không phải “redact sau khi đã tạo full object”. Nó tạo ra telemetry-safe envelope ngay từ đầu. Ví dụ dưới đây là pattern minh họa; tên attribute cần map theo SDK và semantic convention bạn dùng.

import crypto from "node:crypto";

type DataClass = "public" | "internal" | "restricted" | "secret";
type SafeAction = "allow" | "summarize" | "tokenize" | "redact" | "drop";

type SafeField = {
  dataClass: DataClass;
  action: SafeAction;
  fingerprint?: string;
  summary?: string;
  redactedFields?: number;
};

const key = Buffer.from(process.env.TELEMETRY_HMAC_KEY!, "base64");

function fingerprint(value: string): string {
  // Correlation key only: rotate key/scope by tenant and do not treat this as anonymization.
  return crypto.createHmac("sha256", key).update(value).digest("base64url").slice(0, 20);
}

function inspectForTelemetry(input: string, kind: "prompt" | "tool_result"): SafeField {
  if (/authorization:\s*bearer/i.test(input) || /(?:api[_-]?key|password)=/i.test(input)) {
    return { dataClass: "secret", action: "redact", redactedFields: 1 };
  }
  if (/\b\d{3}-\d{2}-\d{4}\b/.test(input) || /\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(input)) {
    return { dataClass: "restricted", action: "redact", redactedFields: 1 };
  }
  return {
    dataClass: "internal",
    action: "summarize",
    fingerprint: fingerprint(input),
    summary: kind === "prompt" ? "intent:account_support" : "result:customer_profile_found",
  };
}

function traceToolCall(span: { setAttribute(k: string, v: string | number | boolean): void }, req: {
  toolName: string;
  schemaVersion: string;
  capability: "read" | "draft" | "write";
  argumentsJson: string;
  resultJson: string;
  durationMs: number;
}) {
  const args = inspectForTelemetry(req.argumentsJson, "prompt");
  const result = inspectForTelemetry(req.resultJson, "tool_result");

  span.setAttribute("agent.tool.name", req.toolName);
  span.setAttribute("agent.tool.schema.version", req.schemaVersion);
  span.setAttribute("agent.tool.capability", req.capability);
  span.setAttribute("agent.tool.duration_ms", req.durationMs);
  span.setAttribute("agent.tool.arguments.action", args.action);
  span.setAttribute("agent.tool.result.action", result.action);
  span.setAttribute("agent.tool.result.class", result.summary ?? "content_redacted");
  span.setAttribute("agent.policy.redacted_fields", (args.redactedFields ?? 0) + (result.redactedFields ?? 0));

  // Deliberately absent: argumentsJson, resultJson, Authorization header, raw prompt.
}

Pattern này không thay thế DLP hay semantic PII detection. Nó đặt một default safe shape: kể cả khi exporter down, retry, sample hay vendor backend thay đổi, code path bình thường cũng chưa từng attach raw payload vào span. Grafana mô tả cùng tinh thần qua SDK-side secret sanitizer: sanitize message, system prompt, tool call và result trước khi generation data được export; server-side guard là lớp bổ sung cho policy tập trung.

Redaction pipeline: phải có nhiều lớp vì mỗi lớp đều có blind spot

Một thiết kế production thường cần ít nhất năm checkpoint.

Đừng dựa vào “redact ở backend sau khi ingest”. Nếu raw prompt đã qua network, queue, retry buffer hoặc SaaS backend, bạn đã mở nhiều bề mặt lưu trữ. OpenTelemetry cung cấp collector processors để modify, filter, redact hoặc transform data—nhưng đồng thời nhấn mạnh cách tốt nhất để không thu thập dữ liệu nhạy cảm là không collect nó ngay từ đầu.

Một pseudo-config có chủ đích allowlist-first có thể được review như sau. Hãy kiểm tra syntax chính xác theo phiên bản Collector của bạn trước khi deploy.

# policy intent, not drop-in configuration
telemetry_policy:
  trace_attributes_allowlist:
    - service.name
    - service.version
    - agent.name
    - agent.version
    - agent.route
    - agent.tool.name
    - agent.tool.capability
    - agent.tool.duration_ms
    - gen_ai.usage.input_tokens
    - gen_ai.usage.output_tokens
    - agent.cost.usd
    - agent.policy.version
    - agent.policy.redacted_fields
  delete_attribute_patterns:
    - ".*prompt.*"
    - ".*message.*"
    - ".*authorization.*"
    - ".*cookie.*"
    - ".*tool.*arguments.*"
    - ".*tool.*result.*"
  export:
    standard_trace_store: metadata_only
    restricted_evidence_store: explicit_break_glass_only

“Tôi sẽ truncate 1.000 ký tự” cũng không an toàn

Truncate giảm volume, không giảm bản chất nhạy cảm. Token có thể nằm ở 20 ký tự đầu; tên, email hay case number cũng vậy. Tương tự, redaction dựa vào regex chỉ mạnh ở pattern đã biết. Tài liệu Grafana phân biệt secret pattern sanitizer với evaluator/guard semantically phát hiện PII—mỗi loại có coverage và trade-off khác nhau; response side, streaming và reasoning block có thể cần control khác.

Đó là lý do cần test pipeline bằng dữ liệu synthetic nhưng độc hại: fake bearer token, email giả, số định danh giả, nested JSON, base64-like string, payload tool chứa header, response streaming. Test không phải để chứng minh redactor “đẹp”; test để chứng minh không có raw value nào xuất hiện trong export mock, dead-letter queue và restricted-store audit ngoài expected lane.

it("never exports a synthetic bearer token in standard telemetry", async () => {
  const fakeSecret = "Bearer test_only_9Qf7r2Kp";
  const span = new MemorySpan();

  traceToolCall(span, {
    toolName: "get_customer_profile",
    schemaVersion: "v4",
    capability: "read",
    argumentsJson: JSON.stringify({ accountRef: "demo-42" }),
    resultJson: JSON.stringify({ upstreamError: `Authorization: ${fakeSecret}` }),
    durationMs: 68,
  });

  const serialized = JSON.stringify(span.attributes);
  expect(serialized).not.toContain(fakeSecret);
  expect(span.attributes["agent.tool.result.action"]).toBe("redact");
  expect(span.attributes["agent.policy.redacted_fields"]).toBe(1);
});

Prompt trace: lưu version, shape và fingerprint; không mặc định lưu transcript

Prompt là nơi teams dễ rơi vào hai cực. Một cực là không lưu gì và không thể reproduce regression. Cực kia là store nguyên system prompt, user input, retrieved chunks, tool schemas và full completion cho mọi request.

Thay vì vậy, hãy tách prompt provenance khỏi prompt content.

Nếu final output bị groundedness regression, hãy bắt đầu với prompt template version, retriever index version, document IDs tokenized, source count, token budget và eval score. Chỉ khi các bằng chứng này không đủ, mới mở restricted evidence theo break-glass workflow. Đây là slow path có chủ đích: nó tạo ma sát trước một hành động privacy-sensitive.

Tool calls: quan sát effect và capability, không chỉ HTTP status

Tool calling là nơi agent observability cần đi xa hơn API logging. HTTP 200 không có nghĩa là an toàn: agent có thể gọi write tool sai tenant; tool trả về PII quá mức; agent có thể loop read tool và tạo denial-of-wallet; hoặc tool success nhưng action phải chờ approval.

OWASP liệt kê tool abuse, excessive autonomy, data exfiltration, prompt injection, denial-of-wallet và sensitive data exposure trong context/logs như rủi ro đặc trưng của agent. Khuyến nghị nền tảng là least privilege, per-tool permission scope, control cho high-impact action, monitoring và data classification.

Một tool span tốt nên mang đủ “hành vi”:

agent.tool.name                 = create_refund_draft
agent.tool.capability            = draft
agent.tool.auth_scope_class      = tenant_limited
agent.tool.argument_shape        = {account_ref: tokenized, amount: bucketed}
agent.tool.result_class          = draft_created
agent.tool.effect                = staged_no_external_side_effect
agent.tool.approval_required     = true
agent.tool.approval_state        = pending
agent.tool.retry_count           = 0
agent.tool.policy_action         = allow

argument_shape không phải JSON raw. Nó là schema classification, ví dụ keys có mặt, type, size bucket và cách xử lý. amount có thể bucket theo range nếu business cần cost/risk insight, thay vì exact amount. account_ref có thể tokenized. Nếu tool là email sender, lưu domain category, recipient count và approval state; đừng lưu email body hoặc recipient address trong default span.

Token, latency và cost: đo tại span, aggregate sau policy

Cost của một agent không nằm ở một model call. Nó nằm ở orchestration: plan, retry, retrieval expansion, tool loop, fallback model và context growth. Vì vậy, mọi LLM span cần có token input/output, model deployment, response finish reason, latency và price-card version; còn root agent span chỉ giữ aggregation đã kiểm soát cardinality.

Một công thức minh họa:

span_cost_usd = (input_tokens / 1_000_000 × input_price_per_million)
              + (output_tokens / 1_000_000 × output_price_per_million)

trace_cost_usd = Σ span_cost_usd + tool_metered_cost_usd

Không hardcode price trong dashboard query. Hãy version hóa price card, capture billing.price_card_version, và coi cost là estimate nếu provider billing hoặc cache semantics không đồng nhất. Numeric cost trong chart bài này là minh họa, không phải claim về giá model.

Ba budget phải tách riêng

cost không được gắn với user email, raw prompt hay full tool args để “giải thích billing”. Hãy dùng route, model class, prompt version, tool name, tenant tier và risk tier—các dimension đã được xem xét cardinality và access. LangChain cũng nhấn mạnh trace có ích để attribute token usage và latency theo step, còn scale production cần sampling/retention policy vì con người không thể review mọi trace.

Sampling và retention: retention dài không phải quan sát tốt hơn

Nếu lưu full payload cho 100% traffic, bạn vừa tăng chi phí vừa mở blast radius. Nếu drop 100% content, đội điều tra hiếm khi bị mù. Câu trả lời không phải một sampling rate cố định, mà là policy dựa theo risk và outcome.

Đây là retention minh họa; luật thực tế phải bám data classification, jurisdiction, contract, threat model và incident policy của tổ chức. Điều không nên thương lượng là mỗi store có owner, access path, TTL và deletion semantics rõ ràng. “Backend observability lưu mãi” không phải retention policy.

Break-glass debugging: nếu cần content, hãy biến nó thành sự kiện audit

Có incident mà metadata không đủ. Có thể tool provider encode lỗi không mong đợi, hoặc prompt injection chỉ thấy rõ trong document fragment. Lúc đó đừng thêm CAPTURE_CONTENT=true toàn cục rồi hứa sẽ tắt sau.

Thiết kế một flow nhỏ, có chủ đích:

1. Engineer mở evidence request với trace.id, lý do và scope field cần xem.
2. Policy engine kiểm tra incident severity, data class, tenant restriction và approver role.
3. Hai principal độc lập phê duyệt nếu content thuộc restricted/secret tier.
4. Chỉ snapshot đã sanitize được decrypt trong viewer chuyên biệt; download/export bị chặn hoặc audit riêng.
5. Access, fields viewed, thời điểm và operator được log; TTL hết thì delete có bằng chứng.
6. Kết quả điều tra được chuẩn hóa thành safe summary và, nếu phù hợp, regression/eval case synthetic.

Cách làm này nghe “nặng”, nhưng nó tạo một boundary có thể audit. Nó cũng ngăn incident response bình thường trở thành pretext xem customer conversation hàng loạt. Tài liệu về redaction của Grafana nêu rõ SDK sanitizer và server guard có coverage khác nhau; không layer nào tự động bảo đảm response, streaming hay model thinking block đều đã được xử lý. Break-glass không thay thế prevention, nhưng là cách thừa nhận nhu cầu điều tra mà không bình thường hóa raw-content access.

Dashboard, alert và runbook: đừng alert trên “token cao” mà không có hành động

Một dashboard tốt không phải gallery của mọi attribute. Nó trả lời cho owner một hành động cụ thể.

Nếu redaction count đột ngột về 0 sau release, đó thường nghiêm trọng hơn latency +100ms. Đừng dựng alert bằng raw payload; alert bằng policy evidence. Một hệ thống observability an toàn phải đo được chính nó: policy version nào xử lý trace, có field nào bị drop, exporter nào bypass, restricted-store access có tăng không.

Các anti-pattern khiến log thành rò rỉ dữ liệu

Kế hoạch 30 ngày: từ console.log đến observability có thể defend

Tuần 1: viết telemetry contract

Inventory mọi field hiện có: SDK auto-capture, custom logs, tool middleware, proxy headers, queue payload và vendor exporter. Với mỗi field, ghi owner, purpose, data class, default action, retention, backend và ai có quyền xem. Nếu field không có purpose, drop nó. Đồng thời xác định 10 câu hỏi incident quan trọng nhất và map mỗi câu sang safe evidence.

Tuần 2: instrument đường nóng

Thêm root agent span, LLM span, retrieval span và tool span. Bật model/version/tokens/duration/tool effect/policy decision; tắt raw content default. Gắn cost card version, retry count, approval state và safe result class. Dựng dashboard cho error, cost, duration, redaction and budget decisions.

Tuần 3: thêm enforcement và tests

Tạo SDK sanitizer, Collector allowlist và canary fixtures. Viết tests chứng minh synthetic secrets không xuất hiện trong exported spans. Test tool error, nested JSON, header, stream chunk và auto-instrumentation. Security và privacy owner review đặc biệt các fields mới.

Tuần 4: vận hành feedback loop

Định nghĩa sampling/retention, mở break-glass process, đưa policy bypass alert vào on-call, và biến safe summaries từ incident thành case cho regression eval. MLflow mô tả observability của agent như tổ hợp tracing, evaluation, monitoring, cost/latency, feedback và governance—đó là feedback loop cần có, không phải các tính năng rời rạc.

Checklist trước khi bật production content tracing

Kết luận

Agent observability trưởng thành không phải là “mọi thứ đều searchable”. Nó là khả năng trả lời nhanh, có bằng chứng: agent đã làm gì, vì sao, tốn bao nhiêu, có vượt policy không và thay đổi nào gây ra hành vi đó—mà không phải nạp prompt, customer data và tool payload vào một kho log rộng mở.

Hãy bắt đầu bằng dữ liệu ít hơn nhưng có cấu trúc hơn: version, trace shape, token/cost, tool effect, policy action và fingerprint có kiểm soát. Sau đó xây restricted evidence lane thật hẹp cho số ít tình huống cần raw context. Nếu không thể nói rõ một field tồn tại để trả lời incident question nào, hãy coi đó là data leak chưa xảy ra, không phải observability chưa hoàn thiện.

Tài liệu tham khảo

[1] OpenTelemetry — Inside the LLM Call: GenAI Observability with OpenTelemetry

[2] OpenTelemetry — Handling sensitive data

[3] Grafana Cloud documentation — PII and secrets redaction

[4] OWASP Cheat Sheet Series — AI Agent Security Cheat Sheet

[5] NIST — Challenges to the Monitoring of Deployed AI Systems

[6] LangChain — AI Agent Observability: Tracing, Testing, and Improving Agents

[7] MLflow — AI Observability for LLMs and Agents