OpenTelemetry GenAI conventions thực tế: thứ gì thật sự được ghi

GenAI conventions của OpenTelemetry đặt tên cho các span mà một app LLM nên tạo, như chat {model} và execute_tool {tool}, và mặc định không ghi prompt. Ngày 26/10/2026, mình chạy bản instrumentation OpenAI chính thức cho Python ở năm cấu hình. Mặc định nó dùng tên attribute cũ, không ghi gì cho Responses API và để span agent, tool cho mình tự viết.

Quy ước yêu cầu gì#

Bộ quy ước nằm trong repository riêng và đang ở trạng thái “Development”, nên tên vẫn có thể đổi (GenAI spans). Những phần một agent cần:

• Lần gọi model là span CLIENT tên {gen_ai.operation.name} {gen_ai.request.model}, ví dụ chat gpt-4o.
• Lần chạy agent là invoke_agent {gen_ai.agent.name}; lần chạy tool là execute_tool {gen_ai.tool.name}, cả hai đều INTERNAL.
• Nhà cung cấp nằm ở gen_ai.provider.name, thay cho gen_ai.system.
• gen_ai.tool.call.id chỉ đặt khi model trả về id. Đừng tự bịa ra.
• Prompt và câu trả lời “SHOULD NOT” được ghi mặc định; muốn ghi thì phải tự bật.

Cài đặt: ghim cả hai gói#

Mình dùng opentelemetry-instrumentation-openai-v2 2.4b0, bản mới nhất trên PyPI hôm đó (PyPI). Cài thẳng thì lỗi ngay lúc import. Gói này đòi opentelemetry-util-genai>=0.4b0.dev, pip chọn bản 1.3b0, và bản đó không còn module mà 2.4b0 import:

ModuleNotFoundError: No module named 'opentelemetry.util.genai.instruments'

Ghim gói phụ về bản phát hành cùng lúc thì chạy được:

pip install "opentelemetry-instrumentation-openai-v2==2.4b0" "opentelemetry-util-genai==0.4b0"

Tên cũ, trừ khi bạn bật quy ước mới#

Mặc định, span chat mang gen_ai.system: openai, và mỗi cặp lần gọi model còn ghi thêm 8 log record, kể cả khi đã tắt nội dung. Với OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental, span chuyển sang gen_ai.provider.name và không còn log record nào. Nếu backend hay dashboard của bạn lọc theo một trong hai tên này, hãy chọn chế độ có chủ đích.

Những thứ nó không ghi#

• Responses API. Gói này chỉ bọc chat.completions.create và embeddings.create. Một lần gọi Responses có stream tạo ra 0 span ở cả năm cấu hình.
• Span agent và tool. Nó chỉ ghi lần gọi model; invoke_agent và execute_tool là phần của bạn, hoặc của framework.
• Nhà cung cấp thật phía sau gateway. Mình gửi một model Gemini qua endpoint tương thích OpenAI, và provider vẫn ghi openai. Tên model, google/gemini-3-flash-preview, mới là trường nói đúng.

Bật ghi prompt: dung lượng và quyền riêng tư#

Ghi nội dung lên span làm dữ liệu span tăng từ 1.210 lên 2.785 byte cho một hội thoại ngắn, tức 2,3 lần. Agent thật gửi lại toàn bộ lịch sử ở mỗi lần gọi, nên phần tăng này cộng dồn.

Tin nhắn thử của mình có tên và địa chỉ email. Khi chạy dữ liệu đã bắt qua bộ lọc thật trên node của Belvador, email thành [Filtered]@example.com. Tên người và phần còn lại của tin nhắn được lưu nguyên. Bộ lọc bắt được mẫu, không hiểu được ý nghĩa, nên lọc PII trong error monitoring phải bắt đầu từ code của bạn. Bộ quy ước gợi ý lưu nội dung ở nơi khác và chỉ đặt tham chiếu lên span.

Belvador ở đâu trong chuyện này#

Belvador nhận span GenAI như mọi span OTLP khác, theo cách cài cho Python, và lưu trên node của bạn. Hướng dẫn quyền riêng tư cho OpenTelemetry xếp nội dung prompt và câu trả lời GenAI vào nhóm nên để tắt. Các span này hiện trong waterfall bình thường; không có màn hình riêng cho LLM. Trang OpenTelemetry có phần tổng quan, còn bài observability cho AI agent cho thấy các span này lộ ra điều gì ở một agent thật. Nếu agent gửi lỗi sang nhà cung cấp AI, bài nơi lưu dữ liệu lỗi và nhà cung cấp AI tách hai lựa chọn đó ra. Tổng quan GenAI conventions liệt kê các loại thao tác khác.