# رصد هوش مصنوعی (Insights)

> https://docs.errora.org/products/insights

Insights همان رصدپذیری مدل‌های زبانی است که روی خط لولهٔ ردیابی ساخته شده. یکپارچه‌سازی‌های
**AI-agents** و **MCP** در SDKهای رسمی Sentry اسپن‌های OpenTelemetry با پیشوند `gen_ai.*` و
`mcp.*` تولید می‌کنند؛ ارورا آن اسپن‌ها را به یک جدول قابل کوئری می‌برد و دو داشبورد می‌سازد.

## راه‌اندازی

محصول جداگانه‌ای برای فعال‌کردن وجود ندارد — ردیابی و یکپارچه‌سازی هوش مصنوعی پشتهٔ خودتان را
روشن کنید.

```python
import sentry_sdk

sentry_sdk.init(
    dsn="…",
    traces_sample_rate=1.0,       # ترافیک AI کم‌حجم و پرارزش است
    send_default_pii=False,       # فقط اگر می‌خواهید پرامپت‌ها ثبت شوند True کنید
)
```

SDK پایتون به‌محض روشن‌شدن ردیابی، OpenAI، Anthropic، LangChain و SDKهای Agents را خودکار
ابزارگذاری می‌کند. در جاوااسکریپت، `Sentry.init({ tracesSampleRate: 1 })` به‌همراه
یکپارچه‌سازی `openAIIntegration()` / `anthropicAIIntegration()` / `vercelAIIntegration()`
همین کار را می‌کند.

برای سرورهای MCP، یکپارچه‌سازی MCP در SDK به ازای هر متد JSON-RPC اسپن `mcp.*` می‌سازد —
همان اسپن‌هایی که [سرور MCP](/products/mcp) خود ارورا هم تولید می‌کند.

:::caution پرامپت و داده‌های شخصی
متن پرامپت و پاسخ فقط وقتی ثبت می‌شود که SDK را برای ارسال آن تنظیم کرده باشید
(`send_default_pii=True` یا گزینهٔ صریح خود یکپارچه‌سازی). تا دلیل روشنی ندارید خاموش
نگهش دارید — پرامپت‌ها معمولاً دادهٔ کاربران را در خود دارند.
:::

## اسپن دستی

اگر مستقیم مدل را صدا می‌زنید، خودتان دورش اسپن بگذارید:

```python
with sentry_sdk.start_span(op="gen_ai.chat", name="summarize") as span:
    span.set_data("gen_ai.system", "openai")
    span.set_data("gen_ai.request.model", "gpt-4o-mini")
    response = client.chat.completions.create(...)
    span.set_data("gen_ai.usage.input_tokens", response.usage.prompt_tokens)
    span.set_data("gen_ai.usage.output_tokens", response.usage.completion_tokens)
```

## داشبورد AI Agents

- **اجرای ایجنت‌ها** در طول زمان، همراه با مدت
- **فراخوانی مدل** — تعداد و تأخیر
- **توکن به تفکیک مدل**، با تفکیک کش‌شده و کش‌نشده
- **فراخوانی ابزارها** — ایجنت واقعاً سراغ کدام ابزارها می‌رود
- **اجراهای اخیر**، که هرکدام یک **خط زمان اسپن‌های همان اجرا** باز می‌کند: گام‌های ایجنت،
  فراخوانی‌های مدل و ابزارهایی که صدا زده، به ترتیب

## داشبورد MCP Server

- **ترافیک** در طول زمان
- **به تفکیک کلاینت** — کدام ایجنت شما را صدا می‌زند
- **به تفکیک متد و لایهٔ انتقال**
- **پرکاربردترین ابزارها، منابع و پرامپت‌ها**

## API

```text
GET /api/v1/projects/{project_id}/insights/agents
GET /api/v1/projects/{project_id}/insights/agents/runs
GET /api/v1/projects/{project_id}/insights/agents/runs/{trace_id}
GET /api/v1/projects/{project_id}/insights/mcp
```

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| داشبوردها خالی‌اند | ردیابی خاموش است یا یکپارچه‌سازی AI فعال نیست — ببینید تراکنش‌ها اسپن `gen_ai.*` دارند یا نه |
| تعداد توکن نیست | پاسخ ارائه‌دهنده اطلاعات مصرف نداشته، یا اسپن دستی `gen_ai.usage.*` را ست نکرده |
| اجراها ناقص به نظر می‌رسند | ترِیس وسط اجرا در نمونه‌برداری حذف شده؛ برای بار کاری AI مقدار `traces_sample_rate` را بالا ببرید |
| پرامپت‌ها دیده می‌شوند و نباید | یکی از گزینه‌ها دارد PII می‌فرستد — `send_default_pii` و پرچم‌های هر یکپارچه‌سازی را بازبینی کنید |