Monitoring and log ingestion

Monitoring combines connected-provider observations with logs submitted to Escanor. Status, logs, analysis, integrations and sections help narrow a problem. A missing signal is not a guarantee that the service is healthy.

Setup and expected results#

Sign in, choose the workspace and connect a supported monitoring/deployment provider. Open Monitoring > Integrations to inspect each source, then choose a time range. Source health and generated timestamps help distinguish recent results from stale data. Sections group related sources; they are not separate provider accounts.

Open Logs, filter by source/level/search and inspect a row's details and surrounding context. Live tail/stream features show newly collected entries while connected; they do not imply that every provider delivers data instantly. If a page is empty, clear the filters and widen the time range before assuming there were no errors.

Custom log ingest key#

Create a named key in Settings > Developer > Log ingest keys. Only owners and admins can manage ingest keys. Choose a source/service name you will recognize in Monitoring. Store the key when it is shown; list views show its prefix and last use, not the secret.

Ingest keys authorize log submission only. They cannot sign in, read collected logs or invoke MCP operations. Revoke a leaked key and replace it in the shipper. Revocation and deleting existing logs are separate actions.

Send a test entry#

curl -fsS https://api.escanor.in/api/v1/observability/ingest \
  -H 'Authorization: Bearer YOUR_LOG_INGEST_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"entries":[{"level":"info","message":"Documentation ingest check","service":"example-service","attrs":{"environment":"staging"}}]}'

Expect HTTP 202 with an accepted count and storage results. Open Monitoring, select the key's source and search for the test message. A 202 with zero accepted entries means the check failed: inspect the payload and current collection preferences.

Accepted payloads and bounds#

The parser accepts a JSON object, an array, an entries/logs/events array wrapper, newline-delimited JSON, plain-text lines and Loki push-shaped streams. Common message, level and time aliases are normalized. Canonical fields include message, level, ts, resource, attrs, status, duration_ms and trace_id.

{"message":"Example request completed","level":"info","duration_ms":42,"status_code":200,"resource":"example-service","attrs":{"route":"/health"}}

Send at most 2,000,000 bytes per request and at most 1,000 entries per batch. The parser caps entries; divide larger batches yourself. Rate limiting returns 429 with Retry-After. Redact secrets and unnecessary personal information before sending; do not rely on downstream redaction to make an unsafe log payload acceptable.

Read API and analysis#

Authenticated user routes under /api/v1/observability include /logs, /logs/tail, /logs/stream, individual log context, overview/source/section analysis and ingest-key management. Reads use the user's session, not an ingest key. Log pages include items, next_cursor and a nullable total; page with the returned cursor instead of computing offsets.

Analysis groups observations and suggests likely causes. Check the evidence/time range and verify at the source before operational changes. Preferences govern collection; a disabled source or collection category cannot produce new data.

Failure recovery#

• 401 on ingest: verify key type and whether it was revoked.
• 413: reduce batch bytes and retry smaller batches.
• 429: wait for Retry-After; reduce send frequency.
• Zero accepted: confirm a nonempty message and enabled collection preferences.
• Missing provider logs: inspect integration health and access scopes.
• Duplicate entries: compare your shipper's retries and request outcomes; do not blindly resend an acknowledged batch.

Related: API and keys, Incidents, Troubleshooting.