Gözlemlenebilirliği kurun

Bir eylem başarısız olduğunda faydalı bilgiler bulun

Gözlemlenebilirlik, uygulamanızın ne yaptığını görmek anlamına gelir. Web sunucunuzu çalıştıran terminalle başlayın: başarısız olan bir eylemi tekrarlayın ve ilk hatayı ve aynı istekten gelen mesajları birbirine bağlayan bir etiket olan herhangi bir korelasyon kimliğini okuyun. Yardım isterken komutu, zamanı ve arındırılmış hatayı paylaşın; .env dosyalarını veya belirteçlerini paylaşmayın.

Barındırılan hata raporları için apps/web/.env.local'de veya ana bilgisayarın ortam panosunda desteklenen izleme ayarlarını yapılandırmak için Sağlık ve işlemler bölümünü izleyin. Sunucuyu kaydedip yeniden başlatın. Test ortamında kontrollü bir test hatasını tetikleyin ve bunun doğru çalışma alanı bağlamında göründüğünü doğrulayın. İzlemenin yapılandırılması, bir olay aldığını kanıtlamaz.

ALERT_WEBHOOK_URL, iş ve terminal web kancası teslim hatası uyarıları için isteğe bağlı bir HTTPS hedefidir. İhtiyacınız varsa uyumlu bir gelen uç noktası oluşturun ve URL sunucu tarafına kaydedin; aksi halde boş bırakın. Bir temsilciden bir arızayı simüle etmesini ve metninde hiçbir sır olmadan tam olarak bir uyarıyı onaylamasını isteyin. Bu test için ücretli çalışmayı veya müşteri hesaplarındaki arızaları tetiklemeyin.

• Uygulama durumunu ve çalışma ayarlarını kontrol edin
• Yerel terminaldeki bir hatayı teşhis edin

Çalışma alanı denetim izi tutun

Denetim kayıtları, çalışma alanı içinde sağlayıcı yapılandırma güncellemeleri gibi değişiklikleri yakalar. Bu kayıtları okumadan ya da yazmadan önce kimliği doğrulanmış çalışma alanını çözün ve ürüne özgü olaylar eklerken o kapsamı koruyun.

Eylemi ve onu anlamak için gereken tanımlayıcıları kaydedin. Sağlayıcı kimlik bilgileri ve diğer hassas değerler denetim yüklerinin ve günlüklerin dışında kalmalıdır.

Ürün olaylarını yakalayın

Gözlemlenebilirlik paketi, AnalyticsClient bağdaştırıcısı ve çalışma alanı kapsamlı AnalyticsEvent değerleri sunar. Her olay ad, belirgin kimlik, workspaceId ve isteğe bağlı özellikler taşır.

Olayları yapılandırılmış analitik istemciniz üzerinden yönlendirmek için createObservability kullanın. Yapılandırılmış özellikler teslimattan önce gizlenir; hassas serbest biçimli metni olay adlarından ve özellik değerlerinden de uzak tutun.

Hataları güvenli bağlamla raporlayın

ErrorClient, workspaceId etiketleri ve yapılandırılmış ek bağlamla istisnaları yakalar. Paylaşılan gözlemlenebilirlik katmanı, yapılandırılmış istemciye iletmeden önce istisnaları temizler ve hassas bağlamı gizler.

İzleme sağlayıcısını çağırmadan yakalanan olayları ve istisnaları doğrulamak için yerel bağdaştırıcıları kullanın. Harici hedefi etkinleştirmeden önce çalışma alanı etiketlerinin mevcut kaldığını ve kimlik bilgilerinin kaldırıldığını test edin.

Görevler, işler ve web kancaları genelinde bir isteği takip edin

Giriş sınırları, kaynak isteği tetiklediği işe bağlayan bir corr_<uuid> korelasyon kimliği içerir. Yapay zeka görevi gönderimi, görev yükünün ve ai_task_subtained olayının üzerindeki kimliği damgalar, her faturalandırma webhook alıcısı istek başına bir tane basar ve zamanlayıcı gönderilen iş başına bir tane basar.

Aynı kimlik, job.completed ve ai_task_completed etkinlik özelliklerini, CaptureException ekstralarını, webhook_event defter yükünü ve her webhook_delivery veri yükünü meta olarak kullanır; böylece abonenin aldığı imzalı gövdenin içine yerleşir. Eksik veya hatalı biçimlendirilmiş kimlikler tolere edilir: Tüketici eski satırları reddetmek yerine yeni bir kimlik basar.

Gerçek arızalar konusunda uyarı

ALERT_WEBHOOK_URL'yi, JSON POST şeklinde bir {metin, ad, önem derecesi, bağlam} kabul eden herhangi bir HTTPS uç noktasına ayarlayın; Slack tarzı bir gelen web kancası olduğu gibi çalışır. Uyarılar, beş saniyelik bir zaman aşımı ile ateşle ve unut şeklindedir, başarısız bir teslimat, bir konsol uyarısını günlüğe kaydeder ve değişken ayarlanmamışken uyarı veren noop'lar.

Gönderilen uyarılar job.failed (uyarı - bir iş yöneticisinin attığı veya iş türü bilinmiyor) ve webhook.delivery_failed (kritik - yalnızca giden teslimat son denemesinden sonra terminal hatasına ulaştığında; sıradan yeniden denemeler sessiz kalır ve her teslimat satırı en fazla bir kez uyarı verir).

Süreleri ölçün ve yapılandırılmış günlükleri yayınlayın

ServerObservability.measure bir eşzamansız işlemin zamanını alır ve başarı ve başarısızlık durumunda, orijinal hatayı maskelemeden, durationMs taşıyan bir <name>.duration analiz olayı yayar. ai.task.execute iş çalıştırması zaten sarmalanmıştır, dolayısıyla görev yürütme süresi yapılandırılmış analiz istemcisine aktarılır.

ServerObservability.logger, ortam ve hizmet tabanı alanlarıyla birlikte stdout'a kayıt başına bir JSON satırı yazar; paylaşılan redaksiyon katmanı, herhangi bir satır yayınlanmadan önce sırları çıkarır.

Kurulum ve yapılandırma

1. Hata raporlama için SENTRY_DSN ayarlayın — istisnalar korelasyon kimlikleri ve çalışma alanı etiketleriyle yakalanır.

2. Ürün analitiği için NEXT_PUBLIC_POSTHOG_KEY ve NEXT_PUBLIC_POSTHOG_HOST ayarlayın — bunlar tasarım gereği herkese açık tarayıcı değerleridir.

3. Hata uyarıları için ALERT_WEBHOOK_URL'yi Slack uyumlu bir uç noktaya ayarlayın — uygulama {text, name, severity, context} JSON'u POST eder.

SENTRY_DSN=https://…@….ingest.sentry.io/…

NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

ANALYTICS_PROVIDER=off    # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=

ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…

Uygulama iş akışı

Gözlemlenebilirlik katmanı, iletmeden önce istisnaları temizler ve bilinen gizli anahtarları gizler — ancak serbest biçimli olay metni yazarın sorumluluğudur, kimlik bilgilerini olay adlarından ve özellik değerlerinden uzak tutun.

Yerel bağdaştırıcılar, Sentry ya da PostHog'u çağırmadan yakalanan olaylara ve istisnalara assertion yazılmasını sağlar; bu değişkenlerin hiçbiri yerelde çalışmak için gerekli değildir.

Sinyaller akıyor mu? Özel alan adlarını kurun ile devam edin.

Doğrulama ve sorun giderme

Bir test istisnası tetikleyin ve sırlar yükten arındırılmış halde Sentry'ye düştüğünü onaylayın, ardından bağlanmış bir hatanın ALERT_WEBHOOK_URL'ye POST ettiğini kontrol edin. Olaylar hiç ulaşmıyorsa DSN/anahtar çiftini ve ana bilgisayarın sunucudan erişilebilir olduğunu doğrulayın.