بخش 7.6 · اکوسیستم

ردگیری محاسبات با LangSmith

LangSmith tracing

فهرست مطالب
  1. نحوه‌ی فعال‌سازی ردگیری محاسبات
  2. ساختار درختی ذخیره‌شده روی سرور
  3. ارسال اجراهای LangChain با وجود مقدار "local"
  4. روش‌های نگه داشتن ردگیری روی سیستم خودتان
  5. هزینه‌ی ردگیری برای هر اجرا
  6. زمان خواندنی‌شدن ردگیری‌ها
  7. کلاینت چه داده‌هایی ارسال می‌کند؟
  8. رفتار سیستم هنگام خطای اندپوینت
  9. محدودیت‌های گزارش‌شده در حساب کاربری

روی اندپوینت میزبانی‌شده‌ی LangSmith API، ردگیری محاسبات (tracing) حدود 6 میلی‌ثانیه به اجرای واقعی ایجنت (agent) اضافه کرد، و مقدار enabled="local" همچنان تمام اجراهای LangChain را به سرور فرستاد.

ردگیری محاسبات را روشن می‌کنید تا ببینید چرا ایجنت ابزار اشتباهی را فراخوانی کرده است. مدتی بعد اندپوینت LangSmith از کار می‌افتد؛ اسکریپت شبانه‌ی شما هنگام خروج معطل می‌ماند و اگر اندپوینت پاسخی ندهد، هرگز خاتمه نمی‌یابد. برای نگه‌داشتن داده‌ها روی سیستم خودتان سراغ tracing_context(enabled="local") می‌روید، اما کلاینت همچنان اجراهای ایجنت را به حسابتان ارسال می‌کند.

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

نحوه‌ی فعال‌سازی ردگیری محاسبات

ردگیری محاسبات (Trace): درختی از اجراها برای یک فراخوانی در بالاترین سطح. هر اجرا شامل نام، نوع اجرا، ورودی‌ها، خروجی‌ها، خطا و اجراهای فرزند خود است.

درخت اجرا (Run tree): شیء درون‌حافظه‌ای یک اجرا؛ یعنی همان RunTree در langsmith. کلاینت هر درخت اجرا را به LangSmith API ارسال می‌کند.

مستندات، ردگیری را در LangChain با دو متغیر فعال می‌کنند: LANGSMITH_TRACING=true و LANGSMITH_API_KEY {{docs langsmith/observability-quickstart}}. حساب‌های خارج از آمریکا متغیر LANGSMITH_ENDPOINT را هم تنظیم می‌کنند. خود SDK در هر فراخوانی با تابع tracing_is_enabled() و طبق اولویت‌های زیر تصمیم می‌گیرد {{code src/langsmith/utils.py}}. این تابع هر متغیر را فقط یک بار در طول عمر فرایند (process) می‌خواند و کش می‌کند؛ پس متغیرها را پیش از اولین فراخوانی تنظیم کنید:

  1. مقدارِ tracing_context جاری، در صورتی که None نباشد.
  2. مقدار True اگر درخت اجرای والد فعال باشد.
  3. مقدار سراسری تنظیم‌شده با langsmith.configure.
  4. متغیر LANGSMITH_TRACING_V2 یا LANGCHAIN_TRACING_V2، و اگر هیچ‌کدام مقدار نداشتند، LANGSMITH_TRACING یا LANGCHAIN_TRACING. ردگیری فقط با رشته‌ی دقیق true فعال می‌شود.

بسته‌ی langsmith جزو وابستگی‌های langchain-core است؛ در نتیجه همه‌ی ایجنت‌ها به این SDK دسترسی دارند. بدون تنظیم این متغیرها، تابعی با دکوراتور traceable یک فراخوانی ساده خواهد بود و هیچ درخت اجرایی تشکیل نمی‌شود:

تابع traceable با غیرفعال بودن ردگیری محاسبات capture/out/42-langsmith.txt
{
  "tracing_is_enabled()": false,
  "result": {
    "answer": "value-for-alpha"
  }
}

get_current_run_tree() inside the call: None

درون tracing_context(enabled="local")، همین تابع یک درخت اجرا می‌سازد. کیت، درخت را تحویل کالبک on_end می‌دهد و آن را ذخیره می‌کند. اجرای فرزند یعنی lookup همان شناسه‌ی ردگیری (Trace ID) والدش را دارد، و مقدار dotted_order آن با ترتیب والد شروع می‌شود:

اجرای فرزند در یک ردگیری محاسبات محلی capture/out/42-langsmith.txt
      "name": "lookup",
      "run_type": "tool",
      "id": "<uuid-2>",
      "trace_id": "<uuid-1>",
      "parent_run_id": "<uuid-1>",
      "dotted_order": "<dotted-time><uuid-1>.<dotted-time><uuid-2>",

اجرای فرزند، محدودشده به فیلدهای هویتی آن.

ساختار درختی ذخیره‌شده روی سرور

یک اجرای LangChain درختی عمیق‌تر می‌سازد: یک اجرای chain برای هر گره گراف، و یک برگ برای هر بار فراخوانی مدل و فراخوانی ابزار (tool call). در بخش 1.3 این درخت برای یک نوبت گردش ایجنت (agent turn) رسم شده است.

ما این درخت را با یک حساب کاربری جدید و رایگان روی اندپوینت ابری و از روی مک اندازه‌گیری کردیم. ایجنت از نوع create_agent به همراه مدل Qwen3 4B روی Ollama و یک ابزار به نام add بود. با استفاده از کلاینت، یک ردگیری ذخیره‌شده را بازخوانی کردیم. این رکورد شامل 7 اجرا با همان نام‌هایی بود که ضبط‌کننده‌ی محلی دریافت کرده بود:

Run Type Parent Tags Tokens
LangGraph chain none none 574
model chain LangGraph graph:step:1 278
ChatOllama llm model seq:step:1 278
tools chain LangGraph graph:step:2 0
add tool tools seq:step:1 0
model chain LangGraph graph:step:3 296
ChatOllama llm model seq:step:1 296

گره‌ی ریشه مجموع توکن‌ها یعنی 545 توکن ورودی و 29 توکن خروجی را نگه می‌دارد. مقدار first_token_time روی ریشه، روی تک‌تک اجراهای model و روی اجراهای llm تنظیم شده است. total_cost در تمام اجراها null است، چون سرور قیمتی برای مدل‌های Ollama ندارد.

فراداده‌ی اجرای llm شامل ls_provider، ls_model_name، ls_temperature و کلیدهای langgraph_* مربوط به گره خود است. کلاینت همچنین LANGSMITH_PROJECT و LANGSMITH_TRACING را داخل فراداده‌ی تک‌تک اجراها کپی می‌کند. فیلد extra.runtime نسخه‌های SDK، کتابخانه‌ها و رشته‌ی مشخصات پلتفرم سیستم را نگه می‌دارد.

همین درخت در نمای ردگیری وب‌اپلیکیشن LangSmith هم دیده می‌شود. تصویر یکی از 30 اجرای ردگیری‌شده روی اندپوینت میزبانی‌شده را بازآفرینی کرده که زمان‌بندی آن‌ها در ادامه آمده است. ایجنت درخواست فراخوانی add(a=305, b=18) را داد و ظرف 6.13 ثانیه پاسخ 323 را برگرداند. دو فراخوانی مدل به ترتیب 3.33 و 2.79 ثانیه طول کشیدند و فراخوانی ابزار کمتر از 0.01 ثانیه زمان برد.

یک اجرای ردگیری‌شده‌ی ایجنت در نمای ردگیری LangSmithیک اجرای create_agent از Qwen3 4B یک ریشه‌ی LangGraph با 6 اجرای فرزند است و دو فراخوانی مدل آن 3.33 و 2.79 ثانیه از 6.13 ثانیه را مصرف می‌کنند.
یک اجرای ردگیری‌شده‌ی ایجنت در نمای ردگیری محاسبات LangSmith بازطراحی نمای ردگیری محاسبات در LangSmith برای یک اجرای create_agent از Qwen3 4B روی Ollama، در پروژه‌ی aiefs-lc101-trace روی پلن رایگان هاست‌شده. قاب سمت چپ درخت اجرا است: ریشه‌ی LangGraph با 6.13 ثانیه و 6 اجرای فرزند، یک گره‌ی مدل 3.33 ثانیه‌ای حاوی فراخوانی ChatOllama با 282 توکن، یک گره‌ی ابزارها شامل ابزار add با 0.00 ثانیه، و یک گره‌ی مدل دوم 2.79 ثانیه‌ای شامل فراخوانی ChatOllama با 302 توکن. یک میله در کنار هر اجرا زمان اجرای آن در طول 6.13 ثانیه را نشان می‌دهد. قاب راست اجرای ریشه است: ورودی پرسش کاربر «حاصل 18 + 305 چیست؟» است، و خروجی شامل پیام کاربر، پیام هوش مصنوعی که add را با a=305 و b=18 صدا می‌زند، نتیجه‌ی ابزار یعنی 323، و پاسخ نهایی هوش مصنوعی یعنی 323 است. LangSmith پروژه‌ی aiefs-lc101-trace، یک اجرا با ردگیری روشن درخت اجرا نمودار آبشاری LangGraph 6.13 ثانیه، 6 اجرای فرزند مدل 3.33 s ChatOllama 3.33 ثانیه، 282 توکن ابزارها 0.00 s add 0.00 s مدل 2.79 s ChatOllama 2.79 ثانیه، 302 توکن ورودی اجرای ریشه کاربر حاصل 18 + 305 چیست؟ خروجی اجرای ریشه کاربر حاصل 18 + 305 چیست؟ AI tool call add(a=305, b=18) add نتیجه‌ی ابزار: 323 AI 323
درخت اجرا در سمت چپ را از بالا، و پیام‌های اجرای ریشه در سمت راست را بخوانید. بازطراحی‌شده از اسکرین‌شات نمای ردگیری محاسبات در پلن رایگان میزبانی‌شده. این اجرا در سطر 58 از capture/lab/T21-langsmith-account-mac/02-e1-timing.jsonl قرار دارد.

ارسال اجراهای LangChain با وجود مقدار "local"

تابع tracing_context مقدارهای True، False، None و رشته‌ی "local" را برای پارامتر enabled می‌پذیرد {{code src/langsmith/run_helpers.py}}. داک‌استرینگ تابع langsmith.configure عملکرد این چهار مقدار را شرح می‌دهد {{code src/langsmith/run_trees.py}}: مقدار True عملیات ردگیری و ارسال را انجام می‌دهد، False ردگیری را خاموش می‌کند، None مقدار را از محیط می‌خواند و "local" عملیات ردگیری را انجام می‌دهد اما داده‌ها را محلی نگه می‌دارد. کدهای بخش traceable در langsmith به این تعهد پایبندند و فقط زمانی اجرا را می‌فرستند که مقدار روی True باشد {{code src/langsmith/run_helpers.py}}.

اما کدهای LangChain چنین رفتاری ندارند. مدیر کالبک‌ها در langchain-core وضعیت را از tracing_is_enabled() استعلام می‌کند و هر پاسخ truthy را معادل روشن در نظر می‌گیرد {{code libs/core/langchain_core/callbacks/manager.py}}. رشته‌ی "local" نیز truthy است؛ در نتیجه مدیر یک LangChainTracer اضافه می‌کند و این ترِیسر تمام اجراها را به سرور می‌فرستد {{code libs/core/langchain_core/tracers/context.py}}. تصویر هر دو مسیر را نشان می‌دهد.

آنچه tracing_context(enabled="local") نگه می‌دارد و ارسال می‌کندیک تابع traceable در کانتکست محلی درخت اجرای خود را نگه می‌دارد، یک ایجنت در همان کانتکست 14 درخواست ارسال می‌کند، و enabled=False همراه با collect_runs هیچ درخواستی نمی‌فرستد.
آنچه tracing_context(enabled="local") نگه می‌دارد و ارسال می‌کند چهار خط حیات: کد شما، رپر traceable در langsmith، مدیریت کال‌بک LangChain، و کلاینت LangSmith. یک تابع traceable درون tracing_context با enabled روی local یک درخت اجرا می‌سازد و به on_end می‌دهد، و کلاینت هیچ درخواستی دریافت نمی‌کند. یک agent.invoke در همان کانتکست ردگیری را فعال می‌کند، چون مدیریت کال‌بک رشته‌ی local را true می‌داند و LangChainTracer را اضافه می‌کند که 7 بار POST /runs و 7 بار PATCH می‌فرستد. همان invoke داخل tracing_context با enabled=False و درون collect_runs چهار اجرای رأس را در حافظه نگه می‌دارد و چیزی نمی‌فرستد. کد شما traceable callbacks کلاینت 1 pipeline() in "local" یک تابع traceable 2 RunTree to on_end در حافظه ماند، 0 درخواست 3 agent.invoke() in "local" کد LangChain 4 ردگیری روشن: "local" مقداری باارزش است LangChainTracer اضافه شد 5 7 بار POST /runs، 7 بار PATCH با وجود محلی بودن، ارسال شد 6 invoke() in enabled=False inside collect_runs() 7 4 runs in traced_runs در حافظه ماند، 0 درخواست
سطرها را از بالا به پایین بخوانید. سطرهای 1 و 2 یک تابع traceable هستند و سطرهای 3 تا 5 ایجنتی در همان کانتکست هستند. سطرهای 6 و 7 مربوط به ایجنت با ردگیری خاموش هستند. از capture/out/42-langsmith.txt.

کیت، یک نوبت گردش ایجنت را درون یک ردگیری محلی قرار می‌دهد و از کلاینتی استفاده می‌کند که نشست (session) مربوط به HTTP آن فقط درخواست‌ها را ثبت می‌کند و چیزی به بیرون نمی‌فرستد:

یک نوبت گردش ایجنت درون tracing_context(enabled="local") capture/out/42-langsmith.txt
HTTP requests the client received for the traceable runs:
{}
…
HTTP requests the client received, by method and path:
{
  "PATCH /runs/<run-id>": 7,
  "POST /runs": 7
}

درخواست‌های اجراهای traceable، سپس درخواست‌های نوبت گردش ایجنت.

ما همین سناریو را روی اندپوینت میزبانی‌شده در مک با langsmith نسخه‌ی 0.14.17 و langchain-core نسخه‌ی 1.8.0 اندازه‌گیری کردیم. فرایند دارای کلید و نام پروژه بود و LANGSMITH_TRACING مقداری نداشت. سه اجرای ایجنت داخل کانتکست "local" هرکدام یک تابع traceable را نیز صدا زدند. همه‌ی 21 اجرای LangChain در قالب 7 درخواست multipart post به سرور رسیدند. سرور پروژه‌ی aiefs-lc101-local را برای آن‌ها ایجاد کرد، اما تابع traceable هیچ داده‌ای نفرستاد:

آنچه سرور برای سه اجرای ایجنت درون enabled="local" ذخیره کرد capture/lab/summary/langsmith-account-mac.json
  "agent_runs": 3,
  "env": [
   "LANGSMITH_API_KEY",
   "LANGSMITH_PROJECT"
  ],
  "multipart_posts": 7,
  "project": "aiefs-lc101-local",
  "project_created": true,
  "stored_runs": {
   "chain LangGraph": 3,
   "chain model": 6,
   "chain tools": 3,
   "llm ChatOllama": 6,
   "tool add": 3
  },
  "traceable_name": "t21_local_traceable",
  "traceable_stored": 0

بنابراین مقدار "local" حتی با یک حساب کاربری واقعی هم هیچ داده‌ای از ایجنت را محلی نگه نمی‌دارد. ما این مشکل را در مخزن langchain-ai/langchain با شماره‌ی #41870 گزارش کردیم.

پیش‌تر همین سناریو را در برابر یک ضبط‌کننده‌ی محلی روی مک بررسی کرده بودیم؛ بدون اندپوینت، بدون کلید و با LANGSMITH_TRACING=false. اجرای ایجنت سعی کرد به هاست پیش‌فرض متصل شود. چون لایه‌ی HTTP را جایگزین کرده بودیم، هیچ داده‌ای از سیستم خارج نشد:

درخواست‌های یک اجرای ایجنت محلی بدون متغیرهای محیطی capture/lab/summary/tracing-mac-real.json
   "case": "local:agent:patched-requests",
   "env": [
    "LANGSMITH_TRACING"
   ],
   "local_trees": 0,
   "request_count": 4,
   "requests": [
    "GET https://api.smith.langchain.com/info",
    "POST https://api.smith.langchain.com/runs/multipart",
    "POST https://api.smith.langchain.com/runs/multipart",
    "POST https://api.smith.langchain.com/runs/multipart"
   ],
   "tracing_is_enabled": "local"

در نتیجه فرایندی که اصلاً کلید ندارد هم همچنان تلاش می‌کند داده‌ها را بفرستد. قرار دادن ایجنت داخل traceable هم کمکی نکرد؛ چون اجراهای لایه‌ی زیرین LangChain باز هم به بیرون ارسال می‌شدند.

روش‌های نگه داشتن ردگیری روی سیستم خودتان

در این نسخه، هیچ متغیر محیطی یا مقداری برای enabled وجود ندارد که هم‌زمان با روشن بودن ردگیری محاسبات، اجراهای LangChain را محلی نگه دارد. به جای آن یکی از این روش‌ها را به کار ببرید:

  • ردگیری محاسبات را برای کدهای LangChain خاموش کنید. فراخوانی را درون tracing_context(enabled=False) قرار دهید. همان‌طور که در اولویت‌بندی بالا آمد، مقدار کانتکست در رتبه‌ی اول بررسی می‌شود؛ بنابراین بر کانتکست بیرونیِ "local" و همه‌ی متغیرها برتری دارد. خالی گذاشتن LANGSMITH_TRACING کافی نیست؛ چون LANGSMITH_TRACING_V2، LANGCHAIN_TRACING_V2 یا یک کانتکست بیرونی باز هم می‌توانند ردگیری را روشن کنند.
  • اجراها را در حافظه جمع‌آوری کنید. تابع collect_runs() از langchain_core.tracers.context جمع‌آورنده‌ای اضافه می‌کند که همه‌ی اجراهای پایان‌یافته را، چه ردگیری روشن باشد چه خاموش، نگه می‌دارد.
  • اندپوینت اختصاصی خود را بالا بیاورید. مقدار LANGSMITH_ENDPOINT را روی یک سرور LangSmith روی سیستم یا شبکه‌ی داخلی خودتان تنظیم کنید. به این ترتیب اجراها از فرایند خارج می‌شوند اما پیش خودتان می‌مانند.
  • از مقدار "local" فقط برای کدهای traceable استفاده کنید. این کار درخت اجرای توابعی را که هیچ کد LangChain صدا نمی‌زنند محلی نگه می‌دارد.

کیت، ایجنت را با ردگیریِ خاموش درون یک کانتکست بیرونیِ "local" اجرا می‌کند و اجراها را جمع می‌آورد:

tracing_context(enabled=False) به همراه collect_runs capture/out/42-langsmith.txt
collect_runs().traced_runs:
[
  "llm ChatOllama",
  "tool add",
  "llm ChatOllama",
  "chain LangGraph"
]

HTTP requests the client received:
{}

متغیر traced_runs اجرای بالایی هر درخت کالبک را به ترتیب پایان یافتنشان نگه می‌دارد. اجرای LangGraph اجراهای مربوط به گره‌ها را به عنوان فرزندان خود دارد. کلاینت هم هیچ داده‌ای دریافت نکرد.

هزینه‌ی ردگیری برای هر اجرا

صفحه‌ی معرفی محصول LangSmith می‌گوید این SDK ردگیری‌ها را در پس‌زمینه می‌فرستد و عملکرد برنامه هرگز تحت تاثیر قرار نمی‌گیرد {{site langchain.com/langsmith/observability}}.

ما رفتار ایجنت را روی اندپوینت میزبانی‌شده در مک سنجیدیم؛ 30 اجرا با ردگیری روشن و 30 اجرا با ردگیری خاموش، به صورت یک‌درمیان در یک فرایند. همه‌ی اجراها پاسخ درست دادند. زمان خارج از مدل را ثبت کردیم: یعنی زمان واقعی (wall time) منهای زمانی که Ollama برای تولید دو پاسخ خود گزارش داد. نخستین اجرای ردگیری‌شده را که 121 میلی‌ثانیه خارج از مدل زمان برده بود، کنار گذاشتیم.

  • ردگیری خاموش: میانه‌ی اجراها 10.9 میلی‌ثانیه خارج از مدل زمان برد.
  • ردگیری روشن: میانه‌ی اجراها 16.9 میلی‌ثانیه خارج از مدل زمان برد.
  • تفاوت: میانه‌ها 5.9 میلی‌ثانیه اختلاف دارند. تحلیل بوت‌استرپ (bootstrap) با 10,000 بار نمونه‌گیری مجدد، بازه‌ی 95 درصدی را بین 3.5 تا 8.6 میلی‌ثانیه نشان می‌دهد.

میانه‌ی زمان واقعی در حالت خاموش 11.66 ثانیه و در حالت روشن 11.78 ثانیه بود. در حین اجرای این دسته (batch)، ایجنت دیگری هم از همان مدل Ollama استفاده می‌کرد؛ به همین دلیل زمان مدل چند ثانیه جابه‌جا شد. از زمان واقعی هیچ نتیجه‌ای نگیرید.

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

زمان خارج از مدل یک اجرای ایجنت با ردگیری خاموش و روشنردگیری محاسبات، میانه‌ی زمان خارج از مدل را از 17.7 میلی‌ثانیه به 26.3 میلی‌ثانیه افزایش داد؛ 7.4 میلی‌ثانیه در مقایسه‌ی جفتی، حدود 1.1 میلی‌ثانیه برای هر یک از هفت اجرای ردگیری‌شده.
زمان خارج از مدلِ یک اجرای ایجنت با ردگیری خاموش و روشن میلی‌ثانیه‌های خارج از مدل به ازای هر اجرای ایجنت Qwen3 4B روی مک، 60 اجرا در هر حالت، به صورت درهم‌آمیخته در یک فرایند. میانه‌ها: خاموش 17.7 میلی‌ثانیه، روشن 26.33 میلی‌ثانیه، 7.42 میلی‌ثانیه بیشتر در جفت‌های اجرا. اجرای میانه با ردگیری روشن 1624.6 میلی‌ثانیه طول کشید. 0 10 20 30 40 50 60 میلی‌ثانیه‌های خارج از مدل 17.7 ms ردگیری خاموش 26.33 ms ردگیری روشن هر نقطه یک اجرای ایجنت از 7 اجرای ردگیری‌شده است، 60 مورد در هر گروه. خط میانه است. رسم نشده: دو اجرای اول. اجرای اول 82.6 میلی‌ثانیه را خارج از مدل سپری کرد.
هر نقطه یک اجرای ایجنت روی مک است؛ 60 مورد برای هر حالت، به صورت متناوب در یک فرایند، و خط مشکی نشان‌دهنده‌ی میانه است. اندپوینت یک ثبات محلی بود که بلافاصله پاسخ می‌داد. از capture/lab/summary/tracing-mac-real.json.

در حالت ضبط‌کننده‌ی محلی، ردگیری محاسبات در جفت‌اجراها 7.4 میلی‌ثانیه اضافه کرد. این عدد به 5.9 میلی‌ثانیه‌ی اندپوینت میزبانی‌شده نزدیک است. در کنار زمان فراخوانی مدل، 6 میلی‌ثانیه ناچیز به نظر می‌رسد؛ اما صفر نیست، و نخستین فراخوانی در فرایندهای کوتاه‌عمر هزینه‌ی بیشتری دارد.

با ضبط‌کننده‌ی محلی، اولین اجرای 6 فرایند از 7 فرایند ردگیری‌شده، بین 83 تا 243 میلی‌ثانیه خارج از مدل زمان برد. در نخستین اجرای ردگیری‌شده، کلاینت راه‌اندازی می‌شود و تنظیمات را از اندپوینت می‌پرسد.

حالت سومی از ردگیری هم با LANGCHAIN_CALLBACKS_BACKGROUND=false طی سه فرایندِ 21 اجرایی در برابر ضبط‌کننده‌ی محلی آزمایش شد. مستندات می‌گویند مقدار false باعث می‌شود کالبک‌ها منتظر بمانند {{docs langsmith/trace-with-langchain}}، اما در کدهای langchain-core نسخه‌ی 1.8.0 یا langsmith نسخه‌ی 0.14.17 هیچ کدی آن را نمی‌خواند. فقط دو پکیج نام آن را آورده‌اند: langgraph-cli آن را در دستور deploy به عنوان متغیر رزروشده فهرست کرده {{code libs/cli/langgraph_cli/deploy.py:76}} (خط 71 فایل wheel در نسخه‌ی 0.4.43)، و langgraph-api نسخه‌ی 0.18.0 مقدار آن را برای ورکر جاوااسکریپت خود برابر با true می‌گذارد {{code langgraph_api/js/remote.py:119}}. هیچ کد پایتونی آن را نمی‌خواند.

بنابراین این حالت دقیقاً همان کدهای حالت ردگیری روشن را اجرا کرد. این اجراها در فرایندهای مجزا و زیر بار پردازشی 4.6 تا 27.5 انجام شدند؛ به همین دلیل از زمان‌بندی آن‌ها نتیجه‌ای نگرفتیم. سامانه‌ی ثبت، این مغایرت مستندات و کد را با شناسه D111 ثبت کرده است.

زمان خواندنی‌شدن ردگیری‌ها

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

ما این تاخیر (latency) را روی 30 اجرای ردگیری‌شده در اندپوینت میزبانی‌شده سنجیدیم. بعد از بازگشت پاسخ از هر invoke، اسکریپت هر 0.25 ثانیه یک بار (به اضافه‌ی زمان هر بار خواندن)، متد read_run را روی ریشه صدا زد. بنابراین دقت به فاصله‌ی بررسی‌ها و زمان خواندن وابسته است و اعداد زیر تقریبی هستند:

رویداد میانه صدک 90 حداکثر
اجرای ریشه خواندنی است 1.46 ثانیه 2.06 ثانیه 3.57 ثانیه
ریشه زمان پایان و خروجی‌ها را دارد 5.63 ثانیه 7.78 ثانیه 10.49 ثانیه

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

کلاینت چه داده‌هایی ارسال می‌کند؟

ما تمام درخواست‌های 30 اجرای ردگیری‌شده را در اندپوینت میزبانی‌شده ثبت کردیم. کلاینت فقط درخواست‌های POST /runs/multipart فرستاد: سه ارسال به ازای هر اجرای ردگیری‌شده که همگی وضعیت 202 گرفتند. کلاینت هیچ درخواست PATCH و هیچ POST /runs ارسال نکرد. تنها درخواست‌های دیگر، دو مورد GET /info بودند، یکی برای هر کلاینت داخل فرایند:

درخواست‌های 30 اجرای ردگیری‌شده به API هاست‌شده capture/lab/summary/langsmith-account-mac.json
  "requests": {
   "GET /info 200": 2,
   "POST /runs/multipart 202": 90
  },
  "responses_with_rate_limit_headers": 0,

هر درخواست شامل هدر Content-Encoding و هدرهای X-Pre-Compressed-Size و X-Post-Compressed-Size بود. کلاینت وقتی مسیر /info در سرور اجازه دهد، داده‌ها را با zstd فشرده می‌کند {{code src/langsmith/_internal/_background_thread.py:572}} {{code src/langsmith/client.py:3599}}. اندپوینت میزبانی‌شده در /info مقدار zstd_compression_enabled را برابر با true گذاشت. هیچ پاسخی هدر محدودیت نرخ درخواست (rate limit) نداشت.

صفحه‌ی مصرف در مستندات می‌گوید SDK حداکثر 100 اجرا از یک نشست (session) را در قالب یک فراخوانی API ارسال می‌کند {{docs langsmith/usage-and-billing}}. در ضبط‌کننده‌ی محلی همراه با یک مدل واقعی، هر ارسال شامل 1 تا 4 اجرا (عمدتاً 3 یا 4 مورد) بود. کلاینت هم‌زمان با اجرای مدل، هرچه داده داشت می‌فرستاد. در برابر ضبط‌کننده‌ای که برای هر درخواست 2 ثانیه زمان می‌برد، تعداد اجراها در هر ارسال تا 18 مورد هم رسید.

کیت آموزشی با تنظیم auto_batch_tracing=False ارسال دسته‌ای را خاموش می‌کند؛ بنابراین برای هر اجرا یک POST /runs و یک PATCH می‌فرستد. کلاینت پیش‌فرض داده‌ها را در این الگو ارسال نمی‌کند.

رفتار سیستم هنگام خطای اندپوینت

همان صفحه‌ی معرفی محصول می‌گوید در صورت بروز اختلال در سرویس LangSmith، ایجنت به کار عادی خود ادامه می‌دهد {{site langchain.com/langsmith/observability}}. با این حال مستندات ردگیری هشدار می‌دهند که ممکن است فرایند پیش از ارسال همه‌ی لاگ‌ها به پایان برسد {{docs langsmith/trace-with-langchain}}.

ما یک فرایند شامل 50 اجرای ایجنت با مدل Qwen3 4B (در مجموع 350 اجرای ردگیری‌شده) را برای حالت‌های مختلف یک ضبط‌کننده‌ی محلی روی مک آزمایش کردیم. ضبط‌کننده‌ی محلی را می‌توان به دلخواه دچار اختلال کرد، اما اندپوینت میزبانی‌شده چنین امکانی ندارد. تصویر زمان سپری‌شده از آخرین اجرا تا خروج کامل فرایند را نشان می‌دهد.

ثانیه‌های سپری‌شده از آخرین اجرا تا خروج فرایند، به تفکیک اندپوینتتمام اجراهای ایجنت در هر شرایطی پاسخ دادند؛ یک اندپوینت با خطا خروج را 9.9 تا 17.1 ثانیه معطل کرد، و یک اندپوینت هنگ‌کرده فرایند را زنده نگه داشت.
ثانیه‌های سپری‌شده از آخرین اجرا تا خروج فرایند، به تفکیک اندپوینت نمودار نقطه‌ای از زمان آخرین اجرای ایجنت تا خروج فرایند روی مک، یک فرایند شامل 50 اجرای ایجنت Qwen3 4B به ازای هر وضعیت اندپوینت. با فراخوانی wait_for_all_tracers در پایان: 0.4 ثانیه در برابر اندپوینت فعال و 0.4 ثانیه در برابر اندپوینت کند. بدون آن: کند 3.7 ثانیه، کند با کال‌بک‌های پس‌زمینه خاموش 3.7 ثانیه، اندپوینتی که 500 برمی‌گرداند 17.1 ثانیه، اندپوینت قطع‌شده 9.9 ثانیه با 0 از 350 اجرای دریافت‌شده، و اندپوینتی که معلق مانده 208 ثانیه پس از آخرین اجرا هنوز زنده بود و در ثانیه‌ی 300 متوقف شد در حالی که 50 از 350 اجرا را دریافت کرده بود. هر اجرای ایجنت پاسخ خود را در هر شرایطی برگرداند. 0 5 10 15 20 ثانیه‌ها از آخرین اجرا تا خروج 0.4 s 350/350 ok flush 0.4 s 350/350 آهسته flush 3.7 s 350/350 آهسته پس‌زمینه خاموش 3.7 s 350/350 آهسته 17.1 s 350/350 بازگشتی‌ها 500 9.9 s 0/350 قطع کشته‌شده 50/350 at 300 s هنگ‌کرده هر نقطه یک فرایند شامل 50 اجرای ایجنت است، در کل 350 اجرای ردگیری‌شده. کسر بالای هر نقطه، اجراهای ردگیری‌شده‌ای است که به اندپوینت رسیده‌اند. flush: wait_for_all_tracers() after the last run. bg off: LANGCHAIN_CALLBACKS_BACKGROUND=false. All 50 runs answered in each process.
هر نقطه یک فرایند شامل 50 اجرای ایجنت Qwen3 4B روی مک است. کسر بالای هر نقطه، اجراهای ردگیری‌شده‌ای است که به اندپوینت رسیدند. اندپوینت هنگ‌کرده یک فلش است، زیرا آن فرایند را در ثانیه‌ی 300 متوقف کردیم. از capture/lab/summary/tracing-mac-real.json.
  • وضعیت اجراها: در همه‌ی حالت‌ها، هر 50 اجرای ایجنت پاسخ درست دادند و هیچ خطایی ایجاد نکردند. ادعای مستندات درباره‌ی اجراها کاملاً درست است.
  • اندپوینتی که قطع است: خروج برنامه 9.9 ثانیه معطل ماند و هیچ‌یک از 350 اجرا به مقصد نرسیدند.
  • اندپوینتی که خطای 500 برمی‌گرداند: کلاینت با احتساب تلاش‌های مجدد 132 درخواست ارسال کرد و خروج برنامه 17.1 ثانیه معطل شد. همه‌ی 350 اجرا به اندپوینت رسیدند و سرور همه‌ی آن‌ها را رد کرد.
  • اندپوینتی که اتصال را قبول می‌کند اما هرگز پاسخی نمی‌دهد: فرایند خودبه‌خود بسته نشد. ما بعد از 300 ثانیه (208 ثانیه پس از آخرین اجرا) آن را متوقف کردیم. تا آن لحظه 50 مورد از 350 اجرا در قالب 6 ارسال از همان 50 اجرا به اندپوینت رسیده بود.
  • اندپوینت کند: با تاخیر 2 ثانیه به ازای هر درخواست، خروج برنامه 3.7 ثانیه طول کشید و همه‌ی 350 اجرا دریافت شدند.

در این نسخه، خروج برنامه منتظر لاگ‌ها ماند؛ بنابراین هشدار مستندات درباره‌ی یک اندپوینت فعال و سالم صدق نمی‌کرد. این هزینه به مرحله‌ی خروج منتقل شد؛ جایی که یک اسکریپت، روال تست، یا یک کنترل‌کننده (handler) در محیط سرورلس هزینه‌اش را می‌پردازد. تابع wait_for_all_tracers() از langchain_core.tracers.langchain را در نقطه‌ای دلخواه از کد صدا بزنید. پس از آن، خروج نهایی تنها 0.4 ثانیه زمان برد. خود عملیات تخلیه‌ی بافر روی ضبط‌کننده‌ی سالم 68 میلی‌ثانیه و روی ضبط‌کننده‌ی کند 4.0 ثانیه طول کشید.

محدودیت‌های گزارش‌شده در حساب کاربری

کلاینت تنظیمات دسته‌ای خود را از مسیر GET /info می‌خواند، و سرور هم محدودیت‌هایش را همان‌جا گزارش می‌کند. ما پاسخ دریافتی از اندپوینت میزبانی‌شده برای حساب کاربری جدید در پلن رایگان را فقط با درخواست‌های GET اندازه‌گیری کردیم:

تنظیمات دسته و محدودیت‌ها در GET /info از API هاست‌شده capture/lab/summary/langsmith-account-mac.json
  "batch_ingest_config": {
   "scale_down_nempty_trigger": 4,
   "scale_up_nthreads_limit": 16,
   "scale_up_qsize_trigger": 1000,
   "size_limit": 100,
   "size_limit_bytes": 20971520,
   "use_multipart_endpoint": true
  },
…
   "max_longlived_ttl_days": 180,
   "per_project_retention_enabled": false,
   "trace_tier_duration_days": {
    "longlived": 400,
    "shortlived": 14
   },
   "trace_tree_max_runs": 1000,

تنظیمات دسته، سپس فلگ‌های نمونه.

  • ارسال دسته‌ای: هر ارسال حداکثر می‌تواند شامل 100 اجرا و 20 مبی‌بایت باشد، و کلاینت از اندپوینت multipart استفاده می‌کند.
  • یک ردگیری: هر ردگیری حداکثر می‌تواند شامل 1,000 اجرا باشد. یک ایجنت عمیق با حلقه‌های طولانی ممکن است به این سقف برسد.
  • مدت نگه‌داری: سطح نگه‌داری پیش‌فرض برای لاگ‌های جدید shortlived است که سیستم آن را مشخص می‌کند. اندپوینت /info این مقدار را 14 روز و برای longlived برابر با 400 روز اعلام می‌کند. متغیر max_longlived_ttl_days عدد 180 را نشان می‌دهد و مقادیر مجاز بین 30 تا 400 روز هستند. متوجه نشدیم در عمل کدام‌یک اعمال می‌شود. قابلیت نگه‌داری به تفکیک پروژه نیز خاموش بود.
  • محدودیت‌های نرخ درخواست: هیچ پاسخی هدر مربوط به محدودیت نرخ درخواست نداشت. اندپوینت /usage-limits یک لیست خالی برگرداند و فیلدهای محدودیت نرخ در سطح سازمان null بودند.
  • پلن کاربری: سازمان فقط امکان تعریف یک فضای کاری و یک شناسه را داشت.

پاسخ اندپوینت GET /sessions هدر deprecation با تاریخ انقضای sunset اول ژوئیه 2027 داشت و /api/v2/sessions را به عنوان جایگزین معرفی کرد. SDK هشدار می‌دهد که list_runs بعد از 31 ژانویه 2027 منسوخ می‌شود، و کد منبع تابع read_run را هم به همین صورت نشانه‌گذاری کرده است {{code src/langsmith/client.py:4063}}. کدهایی که اجراها را می‌خوانند یا فهرست می‌کنند، تا پیش از آن تاریخ باید به فراخوانی‌های جدید تغییر کنند. ما داده‌ی کافی برای رسیدن به هیچ‌کدام از این محدودیت‌ها ارسال نکردیم.

منابع: capture/s_integrations.py، capture/out/42-langsmith.txt؛ capture/lab/summary/langsmith-account-mac.json، capture/lab/T21-langsmith-account-mac/02-e1-timing.jsonl، capture/lab/T21-langsmith-account-mac/02-e1-timing-requests.jsonl، capture/lab/T21-langsmith-account-mac/03-e1-tree.jsonl، capture/lab/T21-langsmith-account-mac/03b-e1-local.json، capture/lab/T21-langsmith-account-mac/01-account-probe.json، capture/lab/T21-langsmith-account-mac/_scripts/t21_e1_trace.py، capture/lab/T21-langsmith-account-mac/_scripts/t21_probe.py؛ capture/lab/summary/tracing-mac-real.json، capture/lab/TRC-tracing-mac-real/04-interleave-summary.jsonl، capture/lab/TRC-tracing-mac-real/03-latency-summary.jsonl، capture/lab/TRC-tracing-mac-real/01-failure-summary.jsonl، capture/lab/TRC-tracing-mac-real/02-tracing-context-local.jsonl، capture/lab/TRC-tracing-mac-real/trc_child_real.py، capture/lab/TRC-tracing-mac-real/trc_driver.py؛ فایلهای src/langsmith/utils.py، src/langsmith/run_helpers.py، src/langsmith/run_trees.py، src/langsmith/client.py و src/langsmith/_internal/_background_thread.py در langsmith نسخه‌ی v0.14.17؛ فایلهای libs/core/langchain_core/callbacks/manager.py، libs/core/langchain_core/tracers/context.py و libs/core/langchain_core/tracers/langchain.py در langchain==1.5.0؛ libs/cli/langgraph_cli/deploy.py در langgraph نسخه‌ی 1.2.22؛ langgraph_api/js/remote.py در langgraph-api نسخه‌ی 0.18.0؛ مستندات docs.langchain.com در commit شماره‌ی 04d4d4a (بخش‌های langsmith/observability-quickstart، langsmith/trace-with-langchain، langsmith/usage-and-billing)؛ صفحه‌ی محصول www.langchain.com/langsmith/observability، تاریخ مشاهده 2026-11-14؛ ایشوی langchain-ai/langchain#41870.

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