آنتروپیک قابلیت Tracing کلاد را عمومی کرد؛ خطایابی بی‌دردسر ایجنت‌های هوش مصنوعی

اضافه شدن قابلیت ردیابی OpenTelemetry به کلاد توسط آنتروپیک

شرکت آنتروپیک (Anthropic) از آغاز فاز بتای عمومی قابلیتی خبر داده که به API کلاد، ایجنت‌های مدیریت‌شده (Managed Agents) و SDKهای کلاد اجازه می‌دهد داده‌های ردیابی (Traces) با استاندارد OpenTelemetry را به هر سرویس یا بَک‌اند سازگار با پروتکل OTLP صادر کنند. بر اساس توضیحات منتشرشده در مستندات نسخه بتا، اسپَن‌های سمت سرور (Server-side Spans) برای درخواست‌های مدل و فراخوانی ابزار‌ها ثبت می‌شوند و به توسعه‌دهندگان این امکان را می‌دهند تا فعالیت‌های Claude را درست در کنار سایر داده‌های تله‌متری اپلیکیشن خود زیر ذره‌بین ببرند.

استاندارد OpenTelemetry یک استاندارد متن‌باز و مستقل از ارائه‌دهنده (Vendor-neutral) برای جمع‌آوری داده‌های ردگیری، معیارها (Metrics) و لاگ‌هاست. در این ساختار، پروتکل OTLP وظیفه جابه‌جایی و انتقال داده‌ها را بر عهده دارد و هر «اسپن» (Span) در واقع یک گزارش زمان‌بندی‌شده از یک عملیات مشخص در طول یک مسیر ردیابی به حساب می‌آید. ترکیب این ابزار‌ها به تیم‌های فنی اجازه می‌دهد تا مسیر حرکت یک درخواست را در سراسر اپلیکیشن، مدل کلاد و ابزار‌های جانبی دنبال کنند، بدون اینکه نیاز باشد یک سیستم مانیتورینگ و نظارت‌پذیری کاملاً مجزا فقط برای لایه مدل هوش مصنوعی راه بیندازند.

دو مسیر متفاوت برای ورود به دنیای ردیابی

نسخه بتای این قابلیت، بسته به اینکه تیم‌ها بخواهند اسپن‌ها را در کدام بخش جمع‌آوری و به هم متصل کنند، دو مسیر یکپارچه‌سازی جداگانه پیش پای توسعه‌دهندگان می‌گذارد: خروجی گرفتن مستقیم از سمت سرور یا ردیابی در سطح اپلیکیشن.

ثبت اسپن‌های سمت سرور بدون نیاز به دستکاری اپلیکیشن

مقاصد تعریف‌شده در بخش کنسول مستقیماً به یک اندپوینت OTLP/HTTP اشاره می‌کنند و اطلاعات هویتی و اعتبارسنجی مورد نیاز سرویس مقصد را در خود دارند. به‌محض اینکه این مقصد برای یک محیط کاری (Workspace) فعال شود، Claude می‌تواند تمام اسپن‌های مربوط به درخواست‌های ارسال‌شده به مدل و فراخوانی ابزار‌ها در آن ورک‌اسپیس را به‌طور خودکار ارسال کند.

هر اسپن از کنوانسیون‌های معنایی gen_ai در OpenTelemetry پیروی می‌کند که نام‌های استانداردی را برای عملیات‌ها و ویژگی‌های هوش مصنوعی مولد تعریف کرده است. در حالت «فقط متادیتا» (Metadata-only)، فیلدهایی مثل مدت زمان اجرا، وضعیت، تعداد توکن‌های مصرفی، نام مدل و نام ابزار‌های استفاده‌شده ثبت می‌شوند. اما در حالت «محتوای کامل» (Full-content)، علاوه بر این اطلاعات، پرامپت‌ها، پاسخ‌های دریافتی، ورودی‌های ارسال‌شده به ابزار‌ها و نتایج بازگشتی آن‌ها هم به‌طور کامل ثبت و ضبط می‌گردد.

البته باید حواستان باشد که ثبت ردیابی با محتوای کامل می‌تواند اطلاعات حساسی مثل کلیدهای دسترسی، داده‌های شخصی، متن‌های اختصاصی محرمانه و خروجی‌های نامطمئن ابزار‌ها را به پلتفرم‌های مانیتورینگ بفرستد. بنابراین تیم‌هایی که قصد دارند این حالت را فعال کنند، باید حتماً مواردی مثل کنترل‌های دسترسی مقصد، سیاست‌های نگهداری داده‌ها، قوانین حذف خودکار داده‌های حساس (Redaction) و الزامات ذخیره‌سازی محلی داده‌ها را به دقت بررسی نمایند.

انعطاف‌پذیری فوق‌العاده در مسیریابی به لطف پروتکل OTLP

آنتروپیک تنظیمات پیش‌فرضی را برای سازگاری آسان با مجموعه‌ای از پلتفرم‌های نظارت عمومی و همچنین سرویس‌های تخصصی تحلیل مدل‌های زبانی ارائه کرده است:

• سرویس‌های Datadog، New Relic، Splunk، Honeycomb و Grafana Cloud
• پلتفرم‌های Sentry و PostHog
• سرویس‌های Arize AI، Braintrust، Langfuse و LangChain
• دیتابریکس (Databricks)
• کالکتورهای محلی OpenTelemetry (سلف‌هاست)

مقاصد سفارشی هم از طریق هر اندپوینت سازگار با OTLP قابل استفاده هستند. اگر از یک کالکتور سلف‌هاست یا اختصاصی استفاده می‌کنید، این کالکتور باید درخواست‌های OTLP/HTTP با انکودینگ protobuf را از طریق آدرس HTTPS و روی پورت ۴۴۳ دریافت کند. از آنجا که این سرویس‌ها معمولاً روی پورت ۴۳۱۸ گوش می‌دهند، در بسیاری از زیرساخت‌ها نیاز است یک ریورس پروکسی (Reverse Proxy) یا لودبالانسر جلوی کالکتور قرار داده شود.

یک مسیر ردیابی یکپارچه بین اپلیکیشن، کلاد و پروتکل MCP

برنامه‌هایی که از کیت توسعه رسمی Claude SDK استفاده می‌کنند، می‌توانند یک Tracer Provider در OpenTelemetry تعریف و ثبت کنند؛ کامپوننتی که وظیفه ایجاد اسپن‌ها و ارسال آن‌ها به پردازنده‌ها و صادرکننده‌های تنظیم‌شده را دارد. پس از تنظیم اولیه، SDK بدون اینکه نیازی به دستکاری فراخوانی‌های تکی Claude باشد، از همین ارائه‌دهنده استفاده خواهد کرد.

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    ConsoleSpanExporter,
    SimpleSpanProcessor,
)

provider = TracerProvider()
provider.add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter())
)
trace.set_tracer_provider(provider)

client = Anthropic()
client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ],
)

هر درخواست خروجی از سمت SDK می‌تواند هدر استاندارد traceparent کنسرسیوم W3C را با خود حمل کند؛ هدی که ردیابی و اسپن والد را مشخص می‌کند. به این ترتیب، وقتی اپلیکیشن شما و سرویس آنتروپیک داده‌ها را به یک بَک‌اند مشترک بفرستند، اسپن‌های API دقیقاً زیر همان اسپن اصلی اپلیکیشن که درخواست را کلید زده بود به نمایش درمی‌آیند.

فلگ نمونه‌برداری (Sampled) در هدر traceparent فرآیند جمع‌آوری داده‌ها در سمت سرور را هم کنترل می‌کند. اگر کلاینت یک درخواست را غیرنمونه‌برداری‌شده (Unsampled) علامت بزند، API اسپن مربوط به آن درخواست و تمام زیرشاخه‌هایش را نادیده می‌گیرد. این قابلیت به سیستم‌ها اجازه می‌دهد تا با استفاده از همان سیاست‌های نمونه‌برداری فعلی خود، حجم سنگین داده‌های تله‌متری را در بارهای کاری پرترافیک ایجنت‌ها مهار کنند.

انتشار این زنجیره ردیابی حتی می‌تواند از طریق کانکتور پروتکل کانتکست مدل (MCP) آنتروپیک هم امتداد یابد. بخش Messages API کانتکست ردیابی را به سرور MCP متصل‌شده پاس می‌دهد و آن سرور هم می‌تواند برای کار‌های اختصاصی خود اسپن‌های فرزند (Child Spans) بسازد. در نتیجه، یک مسیر ردیابی واحد می‌تواند تمام مراحل کار از کدهای اولیه برنامه گرفته تا پردازش‌های Claude و اجرای ابزار‌های جانبی را به‌صورت یکدست پوشش دهد.

تنظیمات و کنترل‌های مدیریت محتوا و حجم داده‌ها

• تنظیم traces.content_mode به‌طور پیش‌فرض روی metadata_only قرار دارد. با تغییر آن به content پرامپت‌ها و پاسخ‌ها نیز ذخیره می‌شوند.
• گزینه traces.max_content_bytes سقف حجم محتوای ضبط‌شده برای هر اسپن را مشخص می‌کند. این مقدار به‌صورت پیش‌فرض ۰.۷۵ مگابایت است و می‌توان متناسب با محدودیت‌های سرور و هزینه‌های ذخیره‌سازی آن را تغییر داد.
• پارامتر conversation_id مقدار gen_ai.conversation.id را پر می‌کند تا بتوان پیام‌های رفت‌وبرگشتی یک مکالمه را دسته‌بندی کرد. از آنجا که این شناسه در هر دو حالت محتوایی ارسال می‌شود، نباید حاوی اطلاعات محرمانه یا هویتی باشد.
• گزینه propagation در شرایطی که ابزار‌های ردیابی HTTP خودتان کانتکست را منتقل می‌کنند، تزریق هدر توسط SDK را غیرفعال می‌سازد.
• دستور open_telemetry=False ردیابی را برای یک کلاینت خاص خاموش می‌کند تا در صورت وجود کتابخانه‌های دیگر، اسپن تکراری ساخته نشود.

در راهنمای کیت توسعه SDK تمامی این گزینه‌ها و معادل متغیرهای محیطی (Environment Variables) آن‌ها به تفصیل شرح داده شده است.

اسپن‌ها چه مشکلاتی را حل و عیب‌یابی می‌کنند؟

درخواست‌های ایجنت‌های هوش مصنوعی معمولاً بسیار پیچیده هستند و به چندین فراخوانی پشت‌سرهم مدل، اجرای ابزارها، جابه‌جایی بین سرور‌های MCP و جریان‌های داده منشعب می‌شوند. در چنین شرایطی، اسپن‌های متصل‌به‌هم دقیقاً آشکار می‌کنند که زمان پردازش و توکن‌ها کجا هدر رفته‌اند، کدام بخش با شکست مواجه شده و سرویس‌های واسط چه نقشی در خروجی نهایی داشته‌اند.

• شناسایی دقیق عامل تاخیر (Latency) و خطاهای رخ‌داده در مدل یا ابزار‌ها
• مشخص کردن میزان مصرف توکن‌های ورودی و خروجی به ازای هر اسپن جداگانه
• ردیابی قدم‌به‌قدم درخواست‌ها در مرزهای میان اپلیکیشن، Claude و پروتکل MCP
• امکان بازبینی پرامپت‌ها و خروجی ابزار‌ها در صورت فعال بودن حالت ذخیره کامل محتوا
• دسته‌بندی تعاملات چندمرحله‌ای با استفاده از شناسه اختصاصی مکالمه

جلسات و نشست‌های ایجنت‌های مدیریت‌شده روی زیرساخت خود آنتروپیک اجرا می‌شوند؛ به همین دلیل لاگ‌های معمولی اپلیکیشن شما هیچ دیدی به سازوکار درونی آن‌ها ندارند. اکنون با خروجی گرفتن از این اسپن‌ها، تمام عملیات سمت سرور مستقیماً به ردگیری اصلی اپلیکیشن اضافه می‌شوند و تیم‌ها می‌توانند با همان داشبوردها و پرس‌وجوهای همیشگی‌شان، عملکرد ایجنت‌ها را ارزیابی و بهینه‌سازی کنند.

محدودیت‌های نسخه بتا و چالش‌های حریم خصوصی

از آنجا که این قابلیت فعلاً در فاز بتا قرار دارد، ممکن است گزینه‌های SDK و ساختار اسپن‌ها در به‌روزرسانی‌های آینده دستخوش تغییر شوند. برای نمونه احتمال دارد آنتروپیک نام برخی اسپن‌ها، اتریبیوت‌ها یا متغیرها را عوض کند که در این صورت کوئری‌ها یا داشبوردهای فعلی شما از کار خواهند افتاد. بنابراین اگر ساختار سیستم شما به این نام‌ها وابسته است، پیشنهاد می‌شود نسخه‌های SDK را ثابت (Pin) نگه دارید و قبل از ارتقا، تغییرات تله‌متری را تست کنید.

مکانیزم تحویل این داده‌ها بر پایه «بیش‌ترین تلاش» (Best-effort) و «حداقل یک بار» (At-least-once) است؛ به این معنی که ممکن است بَک‌اند شما با اسپن‌های تکراری یا گاهی با وقفه‌های لحظه‌ای روبه‌رو شود. بنابراین سیستم‌های دریافت‌کننده باید با استفاده از شناسه‌های Trace و Span موارد تکراری را فیلتر کنند و هرگز این داده‌ها را به چشم یک گزارش رسمی و قطعی ثبت وقایع مالی یا حسابرسی (Audit Log) نگاه نکنند.

آنتروپیک سقف هر سازمان را روی حداکثر ۱۰ مقصد خروجی و ۱۰۰۰ ورک‌اسپیس برای هر مقصد محدود کرده است. سازمان‌هایی که زیرساخت‌های چندمستأجری (Multi-tenant) پیچیده و تفکیک‌شده دارند، باید موقع طراحی دسترسی‌ها و مسیرهای تله‌متری این محدودیت‌ها را مد نظر قرار دهند.

برای سازمان‌هایی که مشمول قوانین حفاظت از داده مانند HIPAA، FERPA یا استانداردهای مدارس K-12 هستند، حالت محتوای کامل ممکن است به‌صورت خودکار و بدون هشدار به حالت «فقط متادیتا» تنزل یابد. با این حال، با توجه به اینکه پارامتر conversation_id در هر دو حالت ارسال می‌شود، باید در انتخاب شناسه‌ها بسیار مراقب باشید تا اطلاعات حساسی لو نرود.

آنتروپیک بابت صدور و ارسال داده‌های OpenTelemetry هیچ هزینه اضافه‌ای دریافت نمی‌کند؛ هرچند پلتفرم‌های مانیتورینگ ممکن است برای دریافت حجم داده، ذخیره‌سازی و اجرای پرس‌وجوها هزینه جداگانه کسر کنند. تیم‌هایی که در حال حاضر از OpenTelemetry استفاده می‌کنند، می‌توانند با خیال راحت و با حفظ سیاست‌های نمونه‌برداری و زیرساخت‌های فعلی، نظارت بر فعالیت‌های کلاد را به داشبوردهای مانیتورینگ خود اضافه نمایند.