समस्या निवारण

यह गाइड आपको उत्पादन में सबसे अधिक संभावित समस्याओं को ठोस निदान और समाधान से जोड़ता है, ताकि आप अतिरिक्त अवलोकन बुनियादी ढांचे को सेट किए बिना पहले से मौजूद उपकरणों से घटनाओं को हल कर सकें। यह सर्वर, कलेक्टर, डैशबोर्ड, एआई असिस्टेंट, Python SDK, स्वास्थ्य और प्रमाणपत्र निगरानी, बैकअप, ClickHouse-समर्थित विश्लेषण और बहु-किरायेदारी को कवर करता है। डैशबोर्ड पृष्ठ /<org-slug>/… के तहत संगठन-स्कोप किए गए हैं, और इवेंट्स स्ट्रीम संगठन मुखपृष्ठ है (/<org-slug>/)। इस गाइड में पृष्ठ के नाम (उदाहरण के लिए /sessions, /queries) उन संगठन-स्कोप किए गए मार्गों को संदर्भित करते हैं।

लॉग्स देखना

AgentEye एक लॉगिंग या निगरानी स्टैक बंडल नहीं करता है। सर्वर और डैशबोर्ड दोनों stdout में संरचित लॉग्स लिखते हैं, इसलिए आप उन्हें kubectl या docker से सीधे पढ़ सकते हैं; कोई एकत्रकर्ता आवश्यक नहीं है।

Kubernetes

सर्वर और डैशबोर्ड के लिए लाइव लॉग्स का पालन करें:

kubectl logs -n agenteye -l app=server    -f --timestamps
kubectl logs -n agenteye -l app=dashboard -f --timestamps

उपयोगी वेरिएंट:

लक्ष्य	कमांड
पिछली 200 लाइनें (कोई पालन नहीं)	`kubectl logs -n agenteye -l app=server --tail=200 --timestamps`
पिछले क्रैश से लॉग्स	`kubectl logs -n agenteye <pod-name> --previous`
सभी प्रतिकृतियों को एक बार टेल करें	`kubectl logs -n agenteye -l app=server --max-log-requests=10 -f`
Postgres (StatefulSet)	`kubectl logs -n agenteye postgres-0 -f`

Docker Compose

docker logs -f agenteye-server
docker logs -f agenteye-dashboard

डैशबोर्ड और सर्वर भर में एक अनुरोध को जोड़ना

हर डैशबोर्ड अनुरोध एक request_id से टैग किया जाता है और x-request-id हेडर के माध्यम से सर्वर को प्रचारित किया जाता है। सर्वर इसे अपने प्रतिक्रिया हेडर में और उस अनुरोध के लिए उत्सर्जित हर लॉग लाइन में दोहराता है। एक अनुरोध को अंत-से-अंत ट्रेस करने के लिए:

प्रतिक्रिया हेडर से आईडी कैप्चर करें, उदाहरण के लिए:
curl -i https://dashboard.example.com/api/events | grep -i x-request-id # x-request-id: 9a7b0d6e-5e9b-4c0a-9f8a-5f1e4b5c0f3a

उस आईडी के लिए दोनों पॉड्स के लॉग्स को grep करें:

REQ=9a7b0d6e-5e9b-4c0a-9f8a-5f1e4b5c0f3a
kubectl logs -n agenteye -l app=dashboard --tail=5000 | grep "$REQ"
kubectl logs -n agenteye -l app=server    --tail=5000 | grep "$REQ"

आप डैशबोर्ड की proxy passthrough, withAuth: authorized, और upstream response लाइनें देखेंगे, साथ ही सर्वर की http request received / http request completed जोड़ी, सभी एक ही request_id साझा करते हुए।

JSON लॉग्स और `jq`

डैशबोर्ड पर AE_LOG_JSON=1 सेट करें (यह डिफ़ॉल्ट रूप से चालू है जब NODE_ENV=production) एक JSON ऑब्जेक्ट प्रति लाइन उत्सर्जित करने के लिए। फिर संरचनात्मक रूप से फ़िल्टर करें:

kubectl logs -n agenteye -l app=dashboard --tail=5000 \
  | jq 'select(.level == "warn" or .level == "error")'

kubectl logs -n agenteye -l app=dashboard --tail=5000 \
  | jq 'select(.route == "POST /api/keys")'

Rust सर्वर tracing key=value जोड़ी उत्सर्जित करता है जो jq के बिना अच्छी तरह से grep करते हैं:

kubectl logs -n agenteye -l app=server --tail=5000 | grep 'status=5'   # 5xx
kubectl logs -n agenteye -l app=server --tail=5000 | grep 'actor_key_id='

वर्बोसिटी को बढ़ाना

घटक	पर्यावरण चर	उदाहरण
सर्वर	`RUST_LOG`	`RUST_LOG=debug` या `RUST_LOG=agenteye_server=debug,info`
डैशबोर्ड	`AE_LOG_LEVEL`	`AE_LOG_LEVEL=debug`

सर्वर पर debug प्रति-प्रमाणीकरण api key authenticated लाइन जोड़ता है। डैशबोर्ड पर debug upstream request, session validated, और proxy passthrough लाइनें जोड़ता है।

लॉग प्रतिधारण

कंटेनर stdout अस्थायी है; kubelet लॉग फ़ाइलों को घुमाता है (डिफ़ॉल्ट ~10 MiB प्रति कंटेनर) और डिस्क पर कुछ रखता है। एक बार पॉड हटाए जाने के बाद लॉग्स चले जाते हैं। यदि आपको लंबी प्रतिधारण या क्रॉस-पॉड खोज की आवश्यकता है, तो अपने क्लस्टर को एक लॉग कलेक्टर (Loki, CloudWatch, Cloud Logging, Datadog, आदि) की ओर इंगित करें जो /var/log/containers/ को टेल करता है। AgentEye किसी विशिष्ट विकल्प की आवश्यकता या निर्धारण नहीं करता है।

प्रमाणीकरण समस्याएं

`docker pull` “unauthorized” के साथ विफल होता है

सुनिश्चित करें कि आपने अपने AGENTEYE_TOKEN के साथ GHCR के विरुद्ध Docker को प्रमाणित किया है:

echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

टोकन में agenteye-enterprise संगठन पर read:packages अनुमति होनी चाहिए। यदि आपका टोकन काम नहीं करता है तो support@exosphere.host से संपर्क करें।

`gh release download` 404 या 401 देता है

पुष्टि करें कि AGENTEYE_TOKEN आपके शेल में निर्यात किया गया है: echo $AGENTEYE_TOKEN
पुष्टि करें कि आप GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download ... का उपयोग कर रहे हैं (the gh CLI GITHUB_TOKEN को पढ़ता है)
टोकन को agenteye-enterprise/releases पर contents:read की आवश्यकता है

सर्वर समस्याएं

सर्वर “invalid port number” के साथ विफल होता है

POSTGRES_PASSWORD (या अन्य क्रेडेंशियल) में URL-विशेष वर्ण (/, +, =) हैं जो DATABASE_URL पार्सिंग को तोड़ते हैं। हेक्स एन्कोडिंग का उपयोग करके पासवर्ड पुनः उत्पन्न करें:

NEW_PASS=$(openssl rand -hex 24)

फिर Kubernetes गोपनीयता और Postgres के अंदर पासवर्ड को अपडेट करें (या Docker Compose के लिए .env को पुनः बनाएं), और सर्वर को पुनरारंभ करें। enterprise-docs/kubernetes-deployment.md § “PostgreSQL credentials” में पूर्ण चरण देखें।

सर्वर स्टार्टअप पर तुरंत बाहर निकलता है

कंटेनर लॉग्स जांचें:

docker logs agenteye-server

सामान्य कारण:

DATABASE_URL सेट नहीं है या विकृत है: सर्वर त्रुटि लॉग करेगा और बाहर निकलेगा।
Postgres पहुंच योग्य नहीं है: पुष्टि करें कि Postgres कंटेनर या प्रबंधित DB चल रहा है और होस्ट/पोर्ट सही हैं।
माइग्रेशन विफल हुए: SQL त्रुटियों के लिए लॉग्स जांचें।

`GET /health` गैर-200 या टाइमआउट देता है

सर्वर पहली शुरुआत पर अभी भी माइग्रेशन चलाया जा रहा है। कुछ सेकंड प्रतीक्षा करें और पुनः प्रयास करें:

curl http://localhost:8080/health

यदि समस्या बनी रहती है, तो त्रुटियों के लिए docker logs agenteye-server जांचें।

`GET /ready` 503 देता है

/ready readiness जांच है: यह 503 देता है जब सर्वर Postgres या ClickHouse तक पहुंच नहीं सकता है। शरीर विफल निर्भरता का नाम बताता है:

curl -s http://localhost:8080/ready
# {"status":"not_ready","checks":{"postgres":"ok","clickhouse":"down","redis":"ok"}}

जो निर्भरता यह down के रूप में रिपोर्ट करता है उसे ठीक करें: क्या ClickHouse/Postgres पॉड Running है? क्या CLICKHOUSE_URL / DATABASE_URL सही और पहुंच योग्य है? Kubernetes पर पॉड NotReady पढ़ता है जब तक /ready ठीक नहीं होता; यह अपेक्षित है और बिल्कुल वह संकेत है जो स्वास्थ्य निगरानी सतर्क करता है। Redis कभी कारण नहीं है: यह रिपोर्ट किया जाता है लेकिन readiness को विफल नहीं करता।

कलेक्टर 401 Unauthorized देता है

कलेक्टर की API कुंजी के पास events:add अनुमति नहीं है, या कुंजी को अक्षम किया गया है। सही अनुमति के साथ एक नई कुंजी बनाएं:

curl -s -X POST http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-collector","permissions":["events:add"]}'

प्रमाणित अनुरोध अचानक धीमे हो गए (~200ms के बजाय ~5ms)

यह Redis के नीचे होने का लक्षण है जबकि REDIS_URL सेट है। हर कैश कॉल 100ms के बाद टाइमआउट करता है फिर Postgres में गिरता है; प्रमाणीकरण और OTP पथों पर अनुरोध दो ऐसे पतन बनाता है। सर्वर लॉग्स में पुष्टि करें:

auth cache: L2 get failed error=redis call timed out

समाधान:

redis-cli -h <your-redis> ping क्लस्टर नेटवर्क पर Redis पहुंच योग्य है यह पुष्टि करने के लिए।
यदि Redis संक्षिप्त रूप से नीचे था और अब वापस है, तो सर्वर पॉड्स को पुनरारंभ करें। redis::aio::ConnectionManager अंतर्निहित कनेक्शन गिरने के बाद विश्वसनीय रूप से पुनः स्थापित नहीं करता; पॉड रीस्टार्ट नई कनेक्शन को साफ-सुथरे तरीके से उठाता है। डैशबोर्ड पर भी वही लागू होता है।
यदि आप अभी Redis नहीं चलाना चाहते हैं, तो तैनाती में REDIS_URL को अनसेट करें और पुनरारंभ करें। दोनों सेवाएं कैश के बिना चलती हैं (शुद्धता संरक्षित है; विलंबता Redis-पूर्व आधारभूत पर वापस आता है)।

सर्वर लॉग्स में `OTP request rate-limited` रिपोर्ट करता है लेकिन उपयोगकर्ता कहता है कि वे केवल एक बार प्रयास करते हैं

जांचें कि क्या Redis अपहुंच्य था। फॉलबैक पथ SELECT COUNT(*) FROM otp_codes WHERE created_at > now() - interval '15 minutes' का उपयोग करता है, जो पहले से उत्पन्न OTP पंक्तियों को देखता है। यदि उपयोगकर्ता एक घंटे के लिए “Resend” पर क्लिक-स्पैम कर रहा है, तो 15-मिनट की विंडो में अभी भी ≥5 कोड हो सकते हैं। विंडो के रोल-ओवर के लिए प्रतीक्षा करके या DELETE FROM otp_codes WHERE user_id = $1 AND created_at > now() - interval '15 minutes' (ऑपरेटर कंसोल) को समाधान करें।

मैंने `ALLOWED_EMAILS` / `SESSION_TTL_SECS` / `OTP_TTL_SECS` बदला और पुनरारंभ किया; कुछ नहीं हुआ

ये env वेरिएबल्स पहली बूट सीड्स केवल हैं। एक बार settings तालिका में मिलान कुंजी के लिए एक पंक्ति होने के बाद, वह पंक्ति सत्य का स्रोत है; env वेरिएबल पहली बूट पर एक बार पढ़ा जाता है और फिर हर बाद की रीस्टार्ट पर अनदेखा किया जाता है। पहली बूट के बाद उन्हें बदलने के लिए, डैशबोर्ड में लॉगिन करें और /settings के तहत उन्हें संपादित करें। परिवर्तन सभी प्रतिकृतियों भर में सेकंड के भीतर लागू होता है; कोई रीस्टार्ट आवश्यक नहीं है। यदि आप env से पुनः-सीड को बल देने की आवश्यकता है (दुर्लभ, आमतौर पर विकास में केवल उपयोगी), DELETE FROM settings WHERE key = '<key>' और सर्वर को पुनरारंभ करें। बूटस्ट्रैप अगली बूट पर वर्तमान env-var मान लेगा। /settings के माध्यम से संपादित करना उत्पादन में समर्थित पथ है।

कलेक्टर समस्याएं

कलेक्टर शुरू होता है लेकिन इवेंट्स डैशबोर्ड में नहीं दिख रहे हैं

पुष्टि करें कि कलेक्टर चल रहा है: systemctl status agenteye-collector (Linux) या प्रक्रिया जांचें।
पुष्टि करें कि AGENTEYE_URL http(s)://your-server-host:8080/events की ओर इंगित करता है (नोट: /events पथ)।
तत्काल आउटपुट देखने के लिए एक-बार फ्लश चलाएं:
agenteye-collector flush
जांचें कि Python SDK वास्तव में फाइलें लिख रहा है: ls ${AGENTEYE_HOME:-~/.agenteye}/events/
यदि ${AGENTEYE_HOME:-~/.agenteye}/failed/ में फाइलें मौजूद हैं, तो अपलोड विफल हो रहे हैं। कलेक्टर लॉग्स में त्रुटि जांचें, संभवतः 4xx (खराब कुंजी या URL) या नेटवर्क समस्या।

फाइलें `$AGENTEYE_HOME/events/` में जमा हो रही हैं और अपलोड नहीं हो रही हैं

कलेक्टर नहीं चल रहा हो सकता है। इसे शुरू करें: agenteye-collector start; यह स्टार्टअप पर पहले से मौजूद इवेंट्स को स्वचालित रूप से फ्लश करता है।
कलेक्टर स्वास्थ्य जांचें: agenteye-collector health
कलेक्टर चल रहा हो सकता है लेकिन सर्वर तक पहुंचने में असमर्थ है। कलेक्टर और सर्वर होस्ट के बीच फायरवाल नियम जांचें।

`$AGENTEYE_HOME/failed/` में फाइलें

सभी पुनः प्रयास प्रयासों (डिफ़ॉल्ट: 5 प्रयास exponential backoff के साथ) के समाप्त होने के बाद फाइलें failed/ में जाती हैं। इसका मतलब है:

सर्वर ने 4xx त्रुटि देी (खराब कुंजी, गलत URL, या पेलोड समस्या)
संपूर्ण पुनः प्रयास विंडो के लिए सर्वर अपहुंच्य था

अंतर्निहित समस्या को ठीक करें, फिर मैन्युअल रूप से पुनः-कतार करें:

mv ${AGENTEYE_HOME:-~/.agenteye}/failed/*.jsonl ${AGENTEYE_HOME:-~/.agenteye}/events/
agenteye-collector flush

कलेक्टर हर अपलोड पर `network error` रिपोर्ट करता है (TLS हैंडशेक विफल)

यदि curl -k के विरुद्ध AGENTEYE_URL सफल होता है लेकिन कलेक्टर बाइनरी error sending request for url (...) के साथ हर अपलोड विफल करता है, तो AgentEye सर्वर एक TLS प्रमाणपत्र प्रस्तुत कर रहा है जो सार्वजनिक रूप से विश्वसनीय CA द्वारा हस्ताक्षरित नहीं है। उत्पादन पथ deploy/base/certificates/domain.env में कॉन्फ़िगर किया गया ACME ingest होस्टनाम है (kubernetes-deployment.md Phase 3.1 / 4.2 देखें)। एक बार INGEST_DOMAIN सार्वजनिक Traefik LB में हल होने के बाद और cert-manager Let’s Encrypt cert जारी कर देता है, कलेक्टर कोई AGENTEYE_TLS_CA की आवश्यकता नहीं; सिस्टम ट्रस्ट स्टोर के विरुद्ध सर्वर cert को सत्यापित करता है; यदि यह पुरानी स्व-हस्ताक्षरित तैनाती के विरुद्ध सेट था तो इसे कलेक्टर कॉन्फ़िग से साफ करें। लक्षण: कलेक्टर कल काम करता था, ~90-दिन के अंतराल के बाद आज विफल हो जाता है। इसका मतलब है तैनाती अभी भी ingest-tls के लिए legacy selfsigned issuer पर है। 90-दिन का प्रमाणपत्र घुमाया गया और pinned CA फाइल पुरानी है। permanently को fix करके deployment guide के Phase 3.1 के लिए क्लस्टर को ACME issuer पर स्विच करें। short-term को अनब्लॉक करें: वर्तमान सर्वर प्रमाणपत्र को पुनः-निकालें और AGENTEYE_TLS_CA को अपडेट करें:

kubectl get secret ingest-tls-cert -n agenteye \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > /etc/agenteye/server-ca.crt

export AGENTEYE_TLS_CA=/etc/agenteye/server-ca.crt
agenteye-collector flush

AGENTEYE_TLS_CA एक अतिरिक्त विश्वास anchors जोड़ता है; मानक सार्वजनिक रूट्स अभी भी विश्वसनीय हैं।

तैनाती के बाद `ingest-tls` Certificate `Ready: False` में फंस गया है

kubectl describe certificate ingest-tls -n agenteye

Events और संदर्भित Order / Challenge देखें। सामान्य कारण:

DNS सार्वजनिक LB को हल नहीं कर रहा है। HTTP-01 वेलिडेटर INGEST_DOMAIN तक नहीं पहुंच सकता। dig +short INGEST_DOMAIN के साथ सत्यापित करें; यह traefik-public LoadBalancer के EXTERNAL-IP के समान पते को हल करना चाहिए। cert-manager स्वचालित रूप से पुनः प्रयास करता है एक बार DNS प्रसारित होता है; प्रमाणपत्र को हटाने की कोई आवश्यकता नहीं है।
पोर्ट 80 लोड बैलेंसर / सुरक्षा समूह पर ब्लॉक किया गया है। HTTP-01 को Let’s Encrypt के सार्वजनिक वेलिडेटर्स से :80 पहुंच योग्य होने की आवश्यकता है। यदि आपके पास अपस्ट्रीम WAF या SG :80 को सीमित कर रहा है, तो इसे खोलें (Traefik कॉन्फ़िग HTTPS में पुनर्निर्देश करता है, लेकिन Boulder पुनर्निर्देश का पालन करता है और प्रतिक्रिया स्वीकार करता है)।
dnsNames प्रतिस्थापित नहीं। यदि kubectl get certificate ingest-tls -n agenteye -o jsonpath='{.spec.dnsNames}' INGEST_DOMAIN_PLACEHOLDER दिखाता है, तो आपने domain.env स्टेप को छोड़ा; इसे domain.env.example से बनाएं और पुनः-लागू करें।
Let’s Encrypt द्वारा Rate limited। एक ही होस्टनाम के लिए बार-बार विफल आदेश डुप्लिकेट-प्रमाणपत्र या विफल-सत्यापन सीमाएं tripped करते हैं। पुनः प्रयास करने से पहले कम से कम एक घंटा प्रतीक्षा करें; सटीक rate-limit संदेश के लिए Order status जांचें।

`dashboard-tls` Certificate `Ready: False` में फंस गया है / ब्राउज़र अभी भी चेतावनी दिखाता है

ingest-tls के समान निदान प्रवाह (kubectl describe certificate dashboard-tls -n agenteye); DNS, port-80, placeholder, और rate-limit कारण सभी लागू होते हैं, साथ ही दो डैशबोर्ड-विशिष्ट भी:

DASHBOARD_DOMAIN गलत LoadBalancer को हल करता है। यह सार्वजनिक ingest के बजाय डैशबोर्ड Traefik LB की ओर इंगित करना चाहिए। होस्टनाम को dig +short करें और डैशबोर्ड LB पते के विरुद्ध तुलना करें।
डैशबोर्ड Traefik इंस्टेंस चुनौती को परोस नहीं सकता है। इसे bundled डैशबोर्ड values फाइल के साथ स्थापित किया जाना चाहिए, जो cert-manager के HTTP-01 solver के लिए scoped Ingress प्रदाता को सक्षम बनाता है। इसके बिना solver अप्राप्य है और Order हमेशा के लिए pending रहता है। प्रदान किए गए values के साथ इंस्टेंस को अपग्रेड करें; pending challenge फिर अपने आप पूरा हो जाता है।
LoadBalancer IP-प्रतिबंधित था। स्रोत रेंज पोर्ट 80 पर भी लागू होती हैं, जो Let’s Encrypt के वेलिडेटर्स को ब्लॉक करता है — पहली जारी और हर ~75-दिन की नवीकरण दोनों। LB को खोलें, या इसे लॉक करने से पहले support के साथ DNS-01 solver का समन्वय करें।

जारी करना विफल होने के दौरान, डैशबोर्ड अपना पिछला प्रमाणपत्र (या ताजी install पर ingress डिफ़ॉल्ट) परोस रहा है — पहुंच ब्राउज़र चेतावनी द्वारा कम हो गया है, कभी नीचे नहीं।

CLI अभी भी TLS सत्यापन को छोड़ता है डैशबोर्ड को विश्वस्त प्रमाणपत्र मिलने के बाद

--insecure को cli.json पर login पर persist किया जाता है। एक बार डैशबोर्ड सार्वजनिक रूप से विश्वसनीय प्रमाणपत्र परोस रहा हो, agenteye --base-url https://<your-dashboard-domain> --secure login के साथ फिर से लॉगिन करें; सत्यापन वापस बचाया जाता है और startup चेतावनी गायब हो जाती है।

डैशबोर्ड समस्याएं

`ADMIN_EMAIL` उपयोगकर्ता को अक्षम या संपादित नहीं कर सकते

डिज़ाइन के अनुसार। ADMIN_EMAIL से मेल खाने वाला उपयोगकर्ता हर सर्वर स्टार्टअप पर protected के रूप में चिह्नित किया जाता है: डैशबोर्ड उस पंक्ति के लिए Disable बटन छुपाता है, और API इसके विरुद्ध DELETE /users/:id और PUT /users/:id को 403 Forbidden के साथ अस्वीकार करता है। एक डेटाबेस ट्रिगर भी प्रत्यक्ष UPDATE स्टेटमेंट को अस्वीकार करता है जो protected पंक्ति को अक्षम करेंगे। बूटस्ट्रैप admin को rotate करने के लिए, अपने environment में ADMIN_EMAIL बदलें और सर्वर को पुनरारंभ करें। नया ईमेल protected के रूप में upserted है। पिछला admin protected ध्वज को retain करता है जब तक डेटाबेस में साफ नहीं किया जाता (आमतौर पर ठीक है, क्योंकि पिछला ईमेल तब तक एक valid admin है जब तक आप स्पष्ट रूप से उन्हें नहीं हटाते)।

डैशबोर्ड कोई इवेंट्स नहीं दिखाता है

डैशबोर्ड के environment वेरिएबल्स (AGENTEYE_SERVER_URL, AGENTEYE_API_KEY) में सर्वर URL और API कुंजी सही हैं यह पुष्टि करें।
डैशबोर्ड API कुंजी को events:read अनुमति की आवश्यकता है।
इवेंट्स वास्तव में ingested हैं यह पुष्टि करें: curl http://your-server:8080/events -H "Authorization: Bearer $ADMIN_KEY"

`/errors` खाली है लेकिन `/events` लाल पंक्तियां दिखाता है

नए SDK संस्करण agent_end / tool_result / hook_completed इवेंट्स के रूप में failures को dedicated event_type: "error" पंक्ति के बजाय पेलोड में outcome: "error" के साथ उत्सर्जित करते हैं। /errors पृष्ठ अब दोनों को जोड़ता है: कोई भी पंक्ति जो /events स्ट्रीम लाल रंग में पेंट करता है (explicit event_type='error', पेलोड outcome/status विफलता सेट में, is_error: true, या truthy error फील्ड) /errors पर दिखाई देता है। यदि आप पहले “/events” पर red पंक्तियों के visible होने के दौरान “no errors in this window” देखते थे, तो डैशबोर्ड + सर्वर को एक साथ अपग्रेड करें (broadened filter errored=true on GET /events है) और दोनों views सहमत होंगे।

`/models`, `/tools`, या `/hooks` wide समय रेंज पर धीमा या लोड करने में विफल है

लक्षण: एक बड़ी events तालिका पर (लाखों पंक्तियां), /models, /tools, या /hooks को खोलना — या समय रेंज को 7d, 30d, या all तक चौड़ा करना — चार्ट स्पिन करते हैं और फिर लोड त्रुटि दिखाते हैं। सर्वर latency_aggregate अनुरोध के लिए ClickHouse MEMORY_LIMIT_EXCEEDED (Code 241) या query timeout को लॉग करता है। कारण: पुरानी builds ने इन पृष्ठों की latency और distribution rollups को एक query के साथ गणना की जो पूरे raw event payload को पढ़ता है और request/response events को एक in-memory sort-and-join के साथ जोड़ता है। Peak query memory इसलिए विंडो के आकार के साथ बढ़ता है, इसलिए एक busy tenant पर एक wide रेंज ClickHouse के per-query memory ceiling को exceed कर सकता है। Fix: इस fix को शामिल करने वाली build में अपग्रेड करें। Rollup अब केवल compact promoted columns को पढ़ता है और events को streaming aggregation के साथ जोड़ता है, इसलिए peak memory अब raw payload के आकार के साथ स्केल नहीं करता है — wide windows memory ceiling के भीतर अच्छी तरह रहते हैं और fraction of time में return होते हैं। सुधार पूरी तरह से query-side है: यह अगले पृष्ठ लोड पर सभी मौजूदा data पर लागू होता है, कोई re-ingest या backfill के बिना।

डैशबोर्ड लोड करने में विफल / blank पृष्ठ

डैशबोर्ड कंटेनर लॉग्स जांचें:

docker logs agenteye-dashboard

सबसे सामान्य कारण AGENTEYE_SERVER_URL या AGENTEYE_API_KEY missing है या unreachable सर्वर की ओर इंगित करता है।

डैशबोर्ड विश्लेषण / टेलीमेट्री

डैशबोर्ड डिफ़ॉल्ट रूप से anonymous product-usage analytics को PostHog को भेजता है, डैशबोर्ड के अपने /ingest पथ के माध्यम से routed (a reverse proxy to https://us.i.posthog.com)। उन्हें first-party के माध्यम से भेजने का मतलब ब्राउज़र ad-blockers उन्हें drop नहीं करते। यह डैशबोर्ड की मुख्य कार्यक्षमता से independent है:

डैशबोर्ड कंटेनर (ब्राउज़र नहीं) वही है जो PostHog तक पहुंचता है। यदि इसकी आउटबाउंड access https://us.i.posthog.com को ब्लॉक किया जाता है, तो टेलीमेट्री silently no-ops; डैशबोर्ड सामान्य रूप से काम करता है और कोई त्रुटियां users को surfaced नहीं होती हैं।
कोई agent, session, या event data कभी included नहीं है, केवल dashboard UI usage।
टेलीमेट्री को पूरी तरह से अक्षम करने के लिए, डैशबोर्ड कंटेनर पर AE_ANALYTICS_DISABLED=1 सेट करें और पुनरारंभ करें। तैनाती guide में Telemetry & privacy देखें।

CLI विश्लेषण / टेलीमेट्री

agenteye CLI डिफ़ॉल्ट रूप से anonymous usage analytics को PostHog को भेजता है: कौन सी commands चलती हैं, success/exit status, और duration। यह CLI की कार्यक्षमता से independent है:

CLI चलाने वाली machine https://us.i.posthog.com सीधे तक पहुंचता है। यदि इसकी आउटबाउंड access ब्लॉक किया जाता है, तो टेलीमेट्री silently no-ops (sending time-bounded है, इसलिए यह कभी command को delay नहीं करता) और CLI सामान्य रूप से काम करता है।
कोई agent, session, या event data कभी included नहीं है: command arguments और flag values (dashboard URL, token, email, session ids, query filters) कभी नहीं भेजे जाते हैं।
इसे अक्षम करने के लिए, CLI के environment में AGENTEYE_ANALYTICS_DISABLED=1 (या cross-tool DO_NOT_TRACK=1) सेट करें। CLI guide में Telemetry & privacy देखें।

एआई असिस्टेंट समस्याएं

पूर्ण setup के लिए enterprise-docs/assistant.md देखें।

असिस्टेंट बुलबुला नहीं दिखाई देता है

बुलबुला hidden है जब तक सभी ये hold नहीं करते:

Signed-in user के पास agent:use अनुमति है।
AGENTEYE_AGENT_URL डैशबोर्ड पर सेट है और agent सेवा पहुंच योग्य है।
एक LLM endpoint agent सेवा पर कॉन्फ़िगर किया गया है (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL के माध्यम से एक gateway, या Bedrock/Vertex)। कोई भी सेट नहीं होने पर, agent “not configured” रिपोर्ट करता है और बुलबुला hidden रहता है।

डैशबोर्ड होस्ट से agent के स्वास्थ्य की जांच करें: curl http://agent:9100/health को {"status":"ok","llm_configured":true,...} return करना चाहिए।

असिस्टेंट कहता है कि यह कुछ नहीं पढ़ सकता

Tools प्रति-user gated हैं। यदि user के पास evaluations:read (या events:read, dashboards:read) नहीं है, तो मिलान tools offered नहीं हैं और असिस्टेंट कहेगा कि यह वह data नहीं पढ़ सकता। प्रासंगिक read अनुमति दें।

भेजते समय “assistant not configured” (HTTP 503)

agent कंटेनर के पास कोई LLM endpoint कॉन्फ़िगर नहीं है, या डैशबोर्ड का AGENTEYE_AGENT_TOKEN agent के से मेल नहीं खाता। दोनों सेट करें और पुनरारंभ करें।

`agent` कंटेनर लोड के तहत restarts / OOMs

प्रत्येक बातचीत एक short-lived child process spawn करता है। सुनिश्चित करें कि कंटेनर एक init process के साथ चलता है (image tini का उपयोग करता है; Compose में init: true सेट करें) और इसे adequate memory limits दें। यदि आवश्यक हो तो AGENTEYE_AGENT_MAX_STEPS को कम करें।

CLI समस्याएं

`agenteye` `ModuleNotFoundError: No module named 'click'` के साथ शुरू करने में विफल

Version 0.1.6 पर agenteye CLI का ताजा install:

ModuleNotFoundError: No module named 'click'

के साथ crash हो सकता है। 0.1.6 click को typer द्वारा indirectly स्थापित किए जाने पर निर्भर था; वर्तमान typer releases अब इसे pull नहीं करते हैं, इसलिए एक clean environment में पैकेज missing हो सकता है। 0.1.7 या नए में अपग्रेड करें, जो click पर directly निर्भर है:

pipx upgrade agenteye      # यदि pipx के साथ स्थापित (या: pipx install --force agenteye)
uv tool upgrade agenteye   # यदि uv के साथ स्थापित
pip install --upgrade agenteye

Install guidance के लिए enterprise-docs/cli.md देखें।

Python SDK समस्याएं

`$AGENTEYE_HOME/events/` में कोई फाइलें नहीं दिख रहीं

SDK events को buffer करता है और डिफ़ॉल्ट रूप से हर 500 ms को flush करता है। यदि आपकी प्रक्रिया flush से पहले exits करती है, तो events खो सकते हैं। short-lived scripts में तेजी से flushing के लिए agenteye.configure(flush_interval=0.1) को कॉल करें, या सुनिश्चित करें कि आपकी प्रक्रिया एक flush cycle के लिए काफी time चलती है। यदि AGENTEYE_HOME सेट है, तो सत्यापित करें कि SDK $AGENTEYE_HOME/events/ में लिख रहा है न कि ~/.agenteye/events/ (requires SDK ≥ 0.0.1b5)।

`ValueError: Reserved field names cannot be used as custom fields`

नाम timestamp, type, और environment reserved हैं और custom fields के रूप में उपयोग नहीं किए जा सकते। इनमें से कोई भी पास करना raise करता है:

ValueError: Reserved field names cannot be used as custom fields: [...]

offensive custom field को rename करें। नोट करें कि session_id और agent_id event call के explicit parameters हैं, custom fields नहीं; किसी को फिर से custom field के रूप में passing करना TypeError raise करता है।

Health Monitoring समस्याएं

Slack में कोई alerts नहीं आ रहे (Robusta)

Robusta health alerting opt-in है; जब तक स्थापित और Slack channel की ओर इंगित नहीं किया जाता है तब तक यह कुछ नहीं भेजता। release और इसके sink को सत्यापित करें:

kubectl get pods -n robusta          # robusta-runner + robusta-forwarder Running होना चाहिए
kubectl logs -n robusta -l app=robusta-runner --tail=50

सामान्य कारण: Slack api_key / slack_channel सेट नहीं थे (या token को revoked किया गया); api_key Robusta cloud-relay token है (robusta integrations slack) लेकिन bundled disableCloudRouting: true को self-hosted Slack bot token (xoxb-…) की आवश्यकता है, या disableCloudRouting: false सेट करें; sink scope उस namespace को exclude करता है जहां आपके pods चलते हैं (bundled values scope to agenteye); या कोई failure अभी नहीं हुआ है। एक pod को नीचे ले जाकर एक test alert को force करें:

kubectl -n agenteye delete pod -l app=clickhouse   # यह recreate होगा

Install और configuration के लिए enterprise-docs/health-monitoring.md देखें।

सर्वर लगातार `NotReady` फ्लैप कर रहा है

Readiness probe /ready को hit करता है, जो Postgres या ClickHouse unreachable होने पर fail होता है। यदि सर्वर NotReady में और बाहर चक्र कर रहा है, तो dependency intermittently unavailable है; ClickHouse और Postgres pods को जांचें और सर्वर के CLICKHOUSE_URL / DATABASE_URL को जांचें। पुष्टि करें कि /ready क्या रिपोर्ट करता है:

kubectl -n agenteye exec deploy/server -- sh -c 'curl -s localhost:8080/ready'

यह probe deliberately tolerant है (एक generous failure threshold), इसलिए sustained flapping एक real dependency समस्या को indicate करता है rather than an over-aggressive probe। Liveness /health पर रहता है, इसलिए flapping readiness pod को नहीं restart करेगा।

Certificate Monitoring समस्याएं

CronJob Slack notifications नहीं भेज रहा है

cert-renewal-check CronJob को एक Secret में stored Slack webhook URL की आवश्यकता है। सत्यापित करें यह मौजूद है:

kubectl get secret cert-renewal-notify-config -n agenteye

यदि missing है, इसे बनाएं:

kubectl create secret generic cert-renewal-notify-config \
  --namespace agenteye \
  --from-literal=SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

Secret के बिना, CronJob अभी भी चलता है और results को stdout में लॉग करता है। Logs को check करें with:

kubectl logs -n agenteye -l job-name --tail=50

Client certificate notification प्राप्त होने से पहले expire हुआ

CronJob हर 12 घंटे चलता है। यदि यह चल नहीं रहा है, तो इसकी status को check करें:

kubectl get cronjob cert-renewal-check -n agenteye

एक manual check trigger करें:

kubectl create job --from=cronjob/cert-renewal-check manual-cert-check -n agenteye
kubectl logs -n agenteye -l job-name=manual-cert-check

Expired certificate को तुरंत re-issue करने के लिए:

cd base/certificates/client-certs
./issue-client-cert.sh <cluster-name>

फिर regenerated collector-mtls-secret.yaml को cluster(s) में apply करें जहां आपके collectors चलते हैं और उन्हें restart करें:

kubectl apply -f collector-mtls-secret.yaml -n <collector-namespace>

Backup समस्याएं

`agenteye-backup` “No space left on device” के साथ विफल

agenteye-backup CronJob Postgres + ClickHouse को एक backup-tmp emptyDir scratch volume (default 30Gi) में dumps करता है, फिर streams tar archive सीधे S3 को — compressed archive कभी scratch में वापस written नहीं है, इसलिए scratch को केवल raw dumps को hold करना है, न dumps + a second on-disk archive copy को। एक pod evicted / No space left on device इसलिए मतलब है कि raw dumps scratch size को exceed करते हैं (ClickHouse events dump dominates और time के साथ बढ़ता है)। Failed job के logs को check करें:

kubectl logs -n agenteye -l job-name=<failed agenteye-backup job>

Fix: आपके overlay में, CronJob के backup-tmp emptyDir sizeLimit को अपने raw dump total से ऊपर raise करें, और सुनिश्चित करें कि node की ephemeral storage वास्तव में इसे hold कर सकता है (sizeLimit एक cap है, न कि एक reservation)। यदि dumps एक single node’s disk को outgrow करते हैं, तो emptyDir को backup-tmp के लिए PVC (EBS/PD) से replace करें, या source पर dumps को compress करें।

पुरानी releases को .tar.gz को dumps के समान 20Gi scratch में लिखता था, इसलिए dumps + archive इसे overflow करता था और pod को before the upload ran से evict किया जाता था — जो S3 failure की तरह लगता है लेकिन वास्तव में disk है। Streaming the upload that doubling को remove करता है।

`agenteye-backup` `curl` install करने में विफल

Job postgres:16 image पर चलता है और ClickHouse HTTP dump के लिए startup पर curl को install करता है। कोई cluster egress के साथ Debian package mirrors के लिए, apt-get step fail होता है। या तो backup pod से उस egress को allow करें, या एक mirrored/custom backup image में curl को bake करें और अपने overlay में इसे reference करें।

`agenteye-backup` चलता है लेकिन कुछ भी object storage में lands नहीं करता है

Base एक real BACKUP_BUCKET (ts-prod-agenteye/backups) और agenteye-backup ServiceAccount ship करता है। Job streams archive को S3 (tar cz … | aws s3 cp - s3://…)। यदि backup pod के पास bucket के लिए write access नहीं है, तो upload errors — और क्योंकि script set -euo pipefail के तहत चलता है, उस pipe में कहीं भी failure पूरे job को upload step में fail करता है rather than silently no-op’ing (pod का EXIT trap backup FAILED during step: upload को logs करता है)। यह भी step है जो आप एक scratch-space eviction को fix करने के बाद reach करते हैं, इसलिए यदि backups पहले archive step पर evicted थे, तो सत्यापित करें कि upload अब lands करता है। Failed job के logs में S3 access error को grep करें:

kubectl logs -n agenteye -l job-name=<failed agenteye-backup job> | grep -iE 's3|upload|denied'

Fix: अपने overlay में BACKUP_BUCKET को एक bucket पर सेट करें जो आप own करते हैं और write access के साथ existing agenteye-backup ServiceAccount को annotate करें (IRSA / Workload Identity / Pod Identity)। enterprise-docs/kubernetes-deployment.md के Backups section को देखें।

ClickHouse-backed evaluations / sessions / queries

तीन tables (events, evaluations, agent_sessions) expected हैं। यदि SchemaBrowser sidebar upgrade के बाद खाली है, तो सर्वर startup पर ClickHouse DDL apply करने में विफल हुआ। failed to apply CH DDL statement के लिए सर्वर logs को check करें:

kubectl logs -n agenteye deploy/server | grep -E 'clickhouse|CH DDL'

सबसे सामान्य कारण ClickHouse unreachable है जबकि migrations चलते हैं। सर्वर CH तक reach नहीं कर सकता तो start करने से refuse करता है, इसलिए एक stuck pod में आमतौर पर CrashLoopBackOff होता है rather than silently broken queries page, लेकिन एक partial DDL apply (एक statement OK, अगले 5xx) schema को half-baked छोड़ देता है। CH को verify reachable करने के बाद server pod को restart करें:

kubectl rollout restart deploy/server -n agenteye

नए evaluations `/sessions` या `/queries` में नहीं दिख रहे हैं

अपग्रेड के बाद, नए evaluations ClickHouse को लिखे जाते हैं, Postgres को नहीं, और /sessions (evaluations:read पर gated) और /queries में surface होते हैं। यदि वे नहीं दिखते हैं:

पुष्टि करें कि evaluator pipeline enabled है (AGENTEYE_AGENT_URL सर्वर पर सेट) और terminal outcomes produce कर रहा है; evaluation_finalized log lines के लिए check करें।
पुष्टि करें कि CH सर्वर से reachable है: kubectl exec -n agenteye deploy/server -- curl -fsS http://clickhouse:8123/ping।
CH table को spot-check करें: kubectl exec -n agenteye clickhouse-0 -- clickhouse-client -q 'SELECT count() FROM agenteye.evaluations'।

Queries लोड के तहत “Memory limit exceeded” के साथ विफल, या ClickHouse `OOMKilled` है

लक्षण: भारी dashboard/query लोड के तहत, analytical pages (the events stream, /sessions, models/latency view, SQL editor) fail होने लगते हैं या timeout करते हैं; सर्वर संक्षिप्त रूप से flaps NotReady; और ClickHouse pod restart count बढ़ता दिखाता है। यह लगभग हमेशा memory है, न कि CPU या disk। पुष्टि करें यह memory है (न कि throughput समस्या जो replication fix करेगा):

Pod को out-of-memory kills के लिए check करें:
kubectl -n agenteye describe pod clickhouse-0 | grep -iE 'Restart Count|Last State|Reason|OOMKilled'
Reason: OOMKilled / Exit Code: 137 एक climbing restart count के साथ tell है।

ClickHouse से पूछें यह क्या reject कर रहा है:

kubectl -n agenteye exec clickhouse-0 -- clickhouse-client -q \
  "SELECT name, value FROM system.errors WHERE value>0 ORDER BY value DESC"

एक large `MEMORY

एआई सहायक

प्रीवियस

​लॉग्स देखना

​Kubernetes

​Docker Compose

​डैशबोर्ड और सर्वर भर में एक अनुरोध को जोड़ना

​JSON लॉग्स और jq

​वर्बोसिटी को बढ़ाना

​लॉग प्रतिधारण

​प्रमाणीकरण समस्याएं

​docker pull “unauthorized” के साथ विफल होता है

​gh release download 404 या 401 देता है

​सर्वर समस्याएं

​सर्वर “invalid port number” के साथ विफल होता है

​सर्वर स्टार्टअप पर तुरंत बाहर निकलता है

​GET /health गैर-200 या टाइमआउट देता है

​GET /ready 503 देता है

​कलेक्टर 401 Unauthorized देता है

​प्रमाणित अनुरोध अचानक धीमे हो गए (~200ms के बजाय ~5ms)

​सर्वर लॉग्स में OTP request rate-limited रिपोर्ट करता है लेकिन उपयोगकर्ता कहता है कि वे केवल एक बार प्रयास करते हैं

​मैंने ALLOWED_EMAILS / SESSION_TTL_SECS / OTP_TTL_SECS बदला और पुनरारंभ किया; कुछ नहीं हुआ

​कलेक्टर समस्याएं

​कलेक्टर शुरू होता है लेकिन इवेंट्स डैशबोर्ड में नहीं दिख रहे हैं

​फाइलें $AGENTEYE_HOME/events/ में जमा हो रही हैं और अपलोड नहीं हो रही हैं

​$AGENTEYE_HOME/failed/ में फाइलें

​कलेक्टर हर अपलोड पर network error रिपोर्ट करता है (TLS हैंडशेक विफल)

​तैनाती के बाद ingest-tls Certificate Ready: False में फंस गया है

​dashboard-tls Certificate Ready: False में फंस गया है / ब्राउज़र अभी भी चेतावनी दिखाता है

​CLI अभी भी TLS सत्यापन को छोड़ता है डैशबोर्ड को विश्वस्त प्रमाणपत्र मिलने के बाद

​डैशबोर्ड समस्याएं

​ADMIN_EMAIL उपयोगकर्ता को अक्षम या संपादित नहीं कर सकते

​डैशबोर्ड कोई इवेंट्स नहीं दिखाता है

​/errors खाली है लेकिन /events लाल पंक्तियां दिखाता है

​/models, /tools, या /hooks wide समय रेंज पर धीमा या लोड करने में विफल है

​डैशबोर्ड लोड करने में विफल / blank पृष्ठ

​डैशबोर्ड विश्लेषण / टेलीमेट्री

​CLI विश्लेषण / टेलीमेट्री

​एआई असिस्टेंट समस्याएं

​असिस्टेंट बुलबुला नहीं दिखाई देता है

​असिस्टेंट कहता है कि यह कुछ नहीं पढ़ सकता

​भेजते समय “assistant not configured” (HTTP 503)

​agent कंटेनर लोड के तहत restarts / OOMs

​CLI समस्याएं

​agenteye ModuleNotFoundError: No module named 'click' के साथ शुरू करने में विफल

​Python SDK समस्याएं

​$AGENTEYE_HOME/events/ में कोई फाइलें नहीं दिख रहीं

​ValueError: Reserved field names cannot be used as custom fields

​Health Monitoring समस्याएं

​Slack में कोई alerts नहीं आ रहे (Robusta)

​सर्वर लगातार NotReady फ्लैप कर रहा है

​Certificate Monitoring समस्याएं

​CronJob Slack notifications नहीं भेज रहा है

​Client certificate notification प्राप्त होने से पहले expire हुआ

​Backup समस्याएं

​agenteye-backup “No space left on device” के साथ विफल

​agenteye-backup curl install करने में विफल

​agenteye-backup चलता है लेकिन कुछ भी object storage में lands नहीं करता है

​ClickHouse-backed evaluations / sessions / queries

​अपग्रेड के बाद /queries पृष्ठ sidebar खाली है

​नए evaluations /sessions या /queries में नहीं दिख रहे हैं

​Queries लोड के तहत “Memory limit exceeded” के साथ विफल, या ClickHouse OOMKilled है