بخش 9.4 · محیط عملیاتی

اسپن‌های OpenTelemetry، بدون LangSmith

OpenTelemetry spans, with LangSmith off

فهرست مطالب
  1. سه نوع اسپن
  2. داخل اسپن‌ها چه بود؟
  3. فراخوانی‌هایی که از دید اسپن‌ها جا می‌مانند
  4. لاگ‌های حامل شناسه‌ی ردگیری
  5. خاموش بودن LangSmith

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

مشتری می‌گوید دستیار در ساعت 10:42 کند بوده و اشتباه جواب داده است. برای بررسی موضوع، به فراخوانی‌های مدل در آن اجرا، تعداد توکن‌هایشان، ابزاری که زمانش تمام شده (Timed out) و خطوط لاگ نیاز دارید؛ همگی با یک شناسه‌ی مشترک. داده‌هایتان نباید از شبکه‌ی داخلی خارج شوند، پس استفاده از سرویس‌های ردگیری محاسبات (Tracing) میزبانی‌شده منتفی است.

با پایان این بخش، می‌توانید سه نوع اسپن (Span) به ایجنت اضافه کنید و آن‌ها را به لاگ‌هایتان پیوند بزنید. همچنین می‌فهمید کدام فراخوانی‌های مدل از دید این اسپن‌ها جا می‌مانند و اثبات می‌کنید که هیچ ردگیری محاسباتی به LangSmith ارسال نمی‌شود.

سه نوع اسپن

اسپن: یک عملیات زمان‌دار با یک نام، مجموعه‌ای از مشخصه‌ها (Attributes)، یک وضعیت (Status) و یک والد. سرویس ما سه نوع اسپن می‌سازد: agent.run که کل یک اجرا را در وظیفه‌ی (Task) اجرایی بخش 9.1 می‌پوشاند؛ و یک میان‌افزار (Middleware) که دور هر فراخوانی مدل یک اسپن model.call و دور هر تلاش برای اجرای ابزار یک اسپن tool.<name> ایجاد می‌کند.

اسپن پیرامون هر فراخوانی مدل capture/lab/prodapp-mac/code/app/middleware.py
class Tracing(AgentMiddleware):
    async def awrap_model_call(self, request, handler):
        with tracer.start_as_current_span("model.call") as span:
            span.set_attribute("gen_ai.request.model", model_id(request.model))
            span.set_attribute("gen_ai.request.message_count", len(request.messages))
            response = await handler(request)
            message = response.result[-1]
            usage = message.usage_metadata or {}
            span.set_attribute("gen_ai.response.model", message.response_metadata.get("model_name", ""))
            span.set_attribute("gen_ai.usage.input_tokens", usage.get("input_tokens", 0))
            span.set_attribute("gen_ai.usage.output_tokens", usage.get("output_tokens", 0))
            span.set_attribute("gen_ai.response.tool_calls", len(message.tool_calls))
            return response

نام مشخصه‌ها از قراردادهای OpenTelemetry برای هوش مصنوعی زایشی پیروی می‌کند. تعداد توکن‌ها هم دقیقاً همان مقادیر ارائه‌دهنده است. برای Ollama، این مقادیر prompt_eval_count و eval_count هستند که توکنایزر خود مدل می‌شمارد. برای Anthropic، همان فیلد usage در پاسخ دریافتی است.

اندازه‌گیری کردیم که آیا وقتی پرامپت از قبل در حافظه‌ی موقت (Cache) باشد، Ollama روی مک باز هم طول کل پرامپت را گزارش می‌کند یا نه. سه فراخوانی یکسان به Qwen3 4B هر کدام مقدار prompt_eval_count را 65 اعلام کردند. ارزیابی پرامپت بار اول 1401.9 میلی‌ثانیه طول کشید (که شامل بارگذاری مدل هم می‌شد)، و در دفعات بعد به 68.6 و 28.7 میلی‌ثانیه رسید. بنابراین این عدد همان طول پرامپت است و برخورد با کش (Cache hit) اثرش را فقط در زمان پاسخ نشان می‌دهد.

خروجی‌گیر (Exporter)، هر اسپن را در قالب یک خط JSON در فایل می‌نویسد. می‌توان بدون دست زدن به میان‌افزار، یک گردآورنده (Collector) یا هر خروجی‌گیر OTLP دیگری را جایگزین آن کرد.

یک اسپن model.call از اجرای Qwen3 14B capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/test-spans.jsonl
{"name": "model.call", "context": {"trace_id": "0xc31ff4d300b6481cedfbf16e6295dbf5", "span_id": "0x2d0efd6deeee8df4", "trace_state": "[]"}, "kind": "SpanKind.INTERNAL", "parent_id": "0x37bcefff7e3ac78d", "start_time": "2026-11-15T10:28:39.576564Z", "end_time": "2026-11-15T10:28:42.578468Z", "status": {"status_code": "UNSET"}, "attributes": {"gen_ai.request.model": "qwen3:14b", "gen_ai.request.message_count": 1, "gen_ai.response.model": "qwen3:14b", "gen_ai.usage.input_tokens": 454, "gen_ai.usage.output_tokens": 22, "gen_ai.response.tool_calls": 1}, "events": [], "links": [], "resource": {"attributes": {"telemetry.sdk.language": "python", "telemetry.sdk.name": "opentelemetry", "telemetry.sdk.version": "1.45.2", "service.instance.id": "a07d9619-8c5e-4163-a075-4db5bf1372bf", "service.name": "support-assistant"}, "schema_url": ""}}

اولین اسپن model.call فایل، در یک سطر.

داخل اسپن‌ها چه بود؟

اسپن‌های اولین اجرای آزمون‌های Qwen3 14B روی مک را اندازه‌گیری کردیم. فایل خروجی شامل 234 اسپن بود: 34 اسپن agent.run، 65 اسپن model.call، 36 اسپن ابزار و 99 اسپن درخواست HTTP. والد همه‌ی 65 اسپن model.call، یک اسپن agent.run بود. هفت اسپن وضعیت ERROR داشتند که هرکدام دقیقاً با یکی از خطاهای تزریق‌شده در آزمون هم‌خوان بود: یک خطا در search_faq، سه خطای تایم‌اوت در read_order، یکی در create_ticket و دو خطا در فراخوانی‌های مدل اصلی.

فریم‌ورک FastAPI نسخه‌ی 0.162.7 نیز از طریق Tracer Provider سراسری، برای هر درخواست اسپن مخصوص خودش را می‌سازد. سرویس ما اسپن‌های عملیاتی داخلی آن را با تنظیم telemetry={"operation_spans": False} غیرفعال می‌کند، اما اسپن‌های درخواست باقی می‌مانند. این اسپن‌ها به کار می‌آیند؛ زیرا یک درخواست کندِ POST /threads/{thread_id}/runs و اسپن agent.run مربوط به آن، شناسه‌ی ردگیری (Trace ID) یکسانی دارند.

فراخوانی‌هایی که از دید اسپن‌ها جا می‌مانند

میان‌افزار SummarizationMiddleware مدل را از طریق هوک اختصاصی خودش فراخوانی می‌کند، یعنی خارج از awrap_model_call. بنابراین هیچ اسپن model.call دور آن تشکیل نمی‌شود {{code libs/langchain_v1/langchain/agents/middleware/summarization.py:520-557}}، و در نتیجه گزارش هزینه‌ای که صرفاً از روی اسپن‌ها ساخته شود، آن را جا می‌اندازد.

سرویس ما علاوه بر این، همه‌ی فراخوانی‌های مدل را از طریق یک Callback در LangChain لاگ می‌کند؛ همراه با میزان مصرف اعلامی ارائه‌دهنده و نام اسپنی که در آن لحظه فعال بوده است. 20 ارزیابی Claude Haiku 5.5 را به همین شیوه و در مقایسه با مصرف ثبت‌شده‌ی Anthropic در دفترکل هزینه‌ها اندازه‌گیری کردیم. در دفترکل، 64 فراخوانی و 76,076 توکن ورودی ثبت شده بود؛ لاگ کال‌بک هم دقیقاً همین 64 فراخوانی و همین مجموع را نشان داد. اگر سناریوی قطعی سرویس را کنار بگذاریم که فراخوانی‌هایش به مدل پشتیبان هدایت شدند، اسپن‌های model.call در مجموع 60,354 توکن از این مقدار را در خود داشتند.

15,722 توکن باقی‌مانده از دو جا ناشی می‌شد: خلاصه‌ساز (Summarizer) در رشته‌پیام 6 نوبته (Turn) و در چرخه‌ی بی‌نهایت، در مجموع 3 فراخوانی با 3,966 توکن ورودی داشت. در سناریوی چرخه‌ی بی‌نهایت نیز میان‌افزار آزمایشی، پاسخ مدل را پس از فراخوانی جایگزین می‌کرد؛ به همین دلیل اسپن‌ها برای 8 فراخوانی صورت‌حساب‌شده با 11,756 توکن ورودی، مقدار 0 توکن را ثبت کردند. این شکاف دوم از خود آزمون می‌آید، اما شکاف اول در تک‌تک اجراهای هر ایجنتی که قابلیت خلاصه‌سازی دارد وجود دارد.

توکن‌های ورودی در هر گفتگو، درون اسپن‌های model.call و بیرون از آن‌هااسپن‌های model.call شامل 60,354 از 76,076 توکن ورودی صورت‌حساب‌شده بودند، و فراخوانی‌های خلاصه‌ساز و پاسخ‌های جایگزین‌شده بقیه را تشکیل دادند.
توکن‌های ورودی در هر گفتگوی ارزیابی با Claude Haiku 5.5، درون و خارج از اسپن‌های model.call 18 گفتگو. 60354 توکن ورودی درون اسپن‌های model.call قرار داشتند، مورد 16 در نظر گرفته نشد و 15722 توکن خارج از آن‌ها صورت‌حساب شدند: فراخوانی‌های خلاصه‌ساز، و فراخوانی‌هایی که میان‌افزار آزمایشی پاسخ آن‌ها را جایگزین کرد. کل مصرف Anthropic برای کل مجموعه 76076 توکن ورودی در 64 فراخوانی و 0.011353 دلار بود. درون اسپن‌های model.call صورت‌حساب‌شده، ولی خارج اسپن model.call 0 5k 10k 15k 20k 25k توکن‌های ورودی در گفتگو 01 02 03 04 05 06 07 08 10 11 12 13 14 15 17 18 19 20 گفتگوی ارزیابی، بر اساس شماره مورد
هر میله نشان‌دهنده‌ی یک گفتگوی ارزیابی با Claude Haiku 5.5 بر اساس شماره‌ی مورد است. رنگ آلوئی نشان‌دهنده‌ی توکن‌های ورودی درون اسپن‌های model.call و رنگ رز نشان‌دهنده‌ی توکن‌های صورت‌حساب‌شده‌ی خارج از آن‌هاست. مورد 9 هیچ مدلی را فراخوانی نمی‌کند و مورد 16 تنها از مدل پشتیبان استفاده کرده است. برگرفته از capture/lab/prodapp-mac/summary/cost-mac.json.

لاگ‌های حامل شناسه‌ی ردگیری

هر خط لاگ به صورت JSON است و فرمت‌کننده، شناسه‌ی ردگیری و شناسه‌ی اسپن مربوط به اسپن جاری را به آن اضافه می‌کند. خطوط زیر مربوط به یک اجرا از سناریوی قفل کردن ابزار (Hung tool) روی Qwen3 14B است. خط لاگ tool.error شناسه‌ی اسپنِ agent.run را دارد، نه شناسه‌ی اسپن ابزار را؛ چرا که ToolErrorMiddleware آن را بیرون از چرخه‌ی تلاش مجدد و پس از پایان آخرین اسپن ابزار می‌نویسد. برای متصل کردن خطوط لاگ به اسپن‌های ابزار، باید از شناسه‌ی ردگیری استفاده کنید.

دو خط لاگ از یک اجرا، متصل‌شده به اسپن‌های آن با trace_id capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/test-log.jsonl
{"ts": 1794738671.926, "level": "INFO", "event": "run.start", "thread_id": "7d6ee462-aeeb-43be-bdc1-320a22f92ee8", "user_id": "e14", "trace_id": "f3619cebe3ac7755ec6e9392b2581a61", "span_id": "5226b37abac5ab4b"}
{"ts": 1794738678.029, "level": "INFO", "event": "tool.error", "tool": "read_order", "error": "TimeoutError", "trace_id": "f3619cebe3ac7755ec6e9392b2581a61", "span_id": "5226b37abac5ab4b"}

خاموش بودن LangSmith

فریم‌ورک LangChain زمانی اجراها را به LangSmith می‌فرستد که مقدار LANGSMITH_TRACING برابر با true باشد. ما LANGSMITH_ENDPOINT را به سمت یک ضبط‌کننده‌ی محلی (Local recorder) هدایت کردیم و یک کلید ساختگی به آن دادیم تا هر تلاشی برای آپلود اطلاعات در قالب یک درخواست دیده شود. سپس یک گفت‌وگو را با مقدار true، یک بار با false و یک بار هم بدون تنظیم این فلگ اجرا کردیم. در هر گفت‌وگو، یک سؤال از بخش سؤالات متداول پرسیده شد، درخواست استرداد وجه همراه با مبلغ و دلیل ثبت شد و سپس با تأییدیه‌ی آن مخالفت شد.

این آزمایش را برای هر حالت، یک بار روی مک و با Qwen3 4B اندازه‌گیری کردیم. مدل در هر سه گفت‌وگو ابزارهای search_faq و refund_order را فراخوانی کرد.

LANGSMITH_TRACING درخواست‌ها به ضبط‌کننده بایت‌ها مسیرها
true 10 337,363 /info، /runs/multipart
false 0 0 هیچ
تنظیم‌نشده 0 0 هیچ

اجرای کنترلی ثابت می‌کند که اگر تلاشی برای ارسال می‌شد، ضبط‌کننده آن را ثبت می‌کرد: 10 درخواست و 337,363 بایت برای یک گفت‌وگوی کوتاه. در دو حالت دیگر هیچ داده‌ای ارسال نشد. صرفِ وجود کلید در متغیرهای محیطی برای ارسال داده کافی نیست؛ تعیین‌کننده خودِ این فلگ است.

منابع: capture/lab/prodapp-mac/code/app/middleware.py، capture/lab/prodapp-mac/code/app/telemetry.py، capture/lab/prodapp-mac/code/app/usage.py، capture/lab/prodapp-mac/code/app/server.py، capture/lab/prodapp-mac/code/scripts/service_real.py، capture/lab/prodapp-mac/code/tests/test_smith_off.py، capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/test-spans.jsonl، capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/test-log.jsonl، capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/usage.jsonl، capture/lab/prodapp-mac/runs/service/service-properties.json، capture/lab/prodapp-mac/runs/ollama-cache-probe.txt، capture/lab/prodapp-mac/runs/suite/haiku/rep-1/usage.jsonl، capture/lab/prodapp-mac/code/scripts/cost_real.py، capture/lab/prodapp-mac/summary/cost-mac.json، capture/lab/prodapp-mac/summary/service-mac.json؛ libs/langchain_v1/langchain/agents/middleware/summarization.py در langchain==1.5.0.

ترجمه‌ی فارسی OpenTelemetry spans, with LangSmith off از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما