لاگ درخواست‌ها

هوشوانا برای هر درخواستی که به API می‌فرستید یک رکورد لاگ ثبت می‌کند. لاگ‌ها به شما کمک می‌کنند بدانید پولتان کجا خرج می‌شود، کدام کلید یا مدل بیشترین مصرف را دارد و چرا یک درخواست خطا گرفته است. لاگ‌ها در https://hooshvana.ir/dashboard/logs در دسترس‌اند.

چه چیزی ثبت می‌شود؟

برای هر درخواست این اطلاعات همیشه ثبت می‌شود:

ثبت بدنه‌ی درخواست و پاسخ

به‌طور پیش‌فرض متن درخواست و پاسخ هم ذخیره می‌شود تا بتوانید هر خطا را دقیق بررسی کنید (حداکثر ۶۴ کیلوبایت از هر بدنه، و تصویر و صوت به شکل base64 حذف می‌شود). این متن‌ها پس از مدت نگهداری حساب پاک می‌شوند. اگر داده‌ی حساس می‌فرستید، ثبت بدنه را خاموش کنید:

• در سطح حساب: برای همه‌ی کلیدها روشن یا خاموش می‌شود.
• در سطح کلید: تنظیم حساب را برای یک کلید خاص بازنویسی می‌کند. جزئیات در قوانین کلید.

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

مدت نگهداری

لاگ‌ها به‌طور پیش‌فرض ۳۰ روز نگهداری می‌شوند و پس از آن حذف می‌شوند. این مدت را می‌توانید در تنظیمات حساب تغییر دهید. اگر به سابقه‌ی طولانی‌تر نیاز دارید (مثلاً برای گزارش مالی)، لاگ‌ها را به صورت دوره‌ای خروجی بگیرید. توجه کنید تراکنش‌های مالی در دفتر کیف پول جداگانه نگهداری می‌شوند و با حذف لاگ از بین نمی‌روند.

فیلتر و خروجی

در صفحه‌ی لاگ‌ها می‌توانید بر اساس این موارد فیلتر کنید:

• بازه‌ی زمانی
• کلید
• مدل
• endpoint
• وضعیت (موفق یا خطا) و کد خطا

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

• کدام کلید این ماه بیشترین هزینه را داشته است؟
• میانگین تأخیر مدل فعلی چقدر است و آیا مدل سریع‌تری لازم داریم؟
• خطاهای rate_limited از کی شروع شده‌اند و مربوط به کدام سرویس‌اند؟

اشکال‌زدایی با شناسه‌ی درخواست

هر پاسخ API یک هدر x-hooshvana-request-id دارد که شناسه‌ی یکتای آن درخواست است. این شناسه را در لاگ‌های برنامه‌ی خودتان ثبت کنید. وقتی مشکلی پیش آمد، می‌توانید با آن درخواست دقیق را در لاگ‌های هوشوانا پیدا کنید و هنگام ارسال تیکت پشتیبانی هم آن را بفرستید تا بررسی سریع‌تر انجام شود.

curl -i https://hooshvana.ir/api/v1/chat/completions \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "سلام"}]}'
# Look for the "x-hooshvana-request-id" header in the output

در Python با with_raw_response به هدرها دسترسی دارید:

import os
from openai import OpenAI

client = OpenAI(base_url="https://hooshvana.ir/api/v1", api_key=os.environ["HOOSHVANA_API_KEY"])

raw = client.chat.completions.with_raw_response.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "سلام"}],
)
request_id = raw.headers.get("x-hooshvana-request-id")
completion = raw.parse()
print(request_id, completion.choices[0].message.content)

در Node.js:

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://hooshvana.ir/api/v1", apiKey: process.env.HOOSHVANA_API_KEY });

const { data, response } = await client.chat.completions
  .create({ model: "openai/gpt-4o-mini", messages: [{ role: "user", content: "سلام" }] })
  .withResponse();

console.log(response.headers.get("x-hooshvana-request-id"), data.choices[0].message.content);

در خطاها هم SDKها هدرها را نگه می‌دارند. مثلاً در Python شیء خطا ویژگی response دارد که می‌توانید x-hooshvana-request-id را از هدرهای آن بخوانید.

حریم خصوصی

• کلید کامل API هرگز در لاگ ذخیره نمی‌شود.
• متن درخواست و پاسخ فقط وقتی ذخیره می‌شود که ثبت بدنه را روشن کرده باشید.
• لاگ‌ها فقط برای خود شما در داشبورد قابل مشاهده‌اند.
• اگر داده‌ی شخصی کاربرانتان را به مدل می‌فرستید، ثبت بدنه را برای آن کلید خاموش نگه دارید و مدت نگهداری را کوتاه کنید.
• در فیلد user درخواست‌ها شناسه‌ی داخلی بفرستید، نه ایمیل یا شماره‌ی تلفن.

لاگ و صورتحساب

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