Setting Up Log Drains

A log drain is a persistent connection that streams your project's runtime logs to an external HTTP endpoint as they are generated. Every log line emitted by your edge functions — including console output, errors, and request traces — is delivered in real time.

Log drains send structured JSON payloads over HTTPS. Each event includes a timestamp, log level, region, deployment ID, and the original message. This format is compatible with most observability platforms out of the box.

‍

What gets forwarded

• All console.log , console.warn ,and console.error output from edge functions
• Unhandled runtime exceptions with stack traces
• Request and response metadata (method, status, latency, region)
• Cron job execution events and outcomes

‍

Delivery guarantees

Log drains use an at-least-once delivery model. In the rare case of a network interruption, events may be retried up to three times with exponential backoff. Your endpoint should be idempotent — it should handle duplicate events without causing data inconsistency.

Step 1 — Create a log drain

Go to your project settings in the dashboard under Observability → Log Drains → New Drain, or create one via the CLI:

# Create a new log drain
vertex drain create \
  --name "my-log-drain" \
  --url https://ingest.example.com/logs \
  --secret your-signing-secret

# List all log drains for the project
vertex drain list

The --secret flag sets a shared signing secret used to generate an HMAC signature for each request. Your endpoint can use this to verify that events are genuinely coming from Vertex.

Tip: You can create multiple log drains per project — for example, one forwarding all logs and another filtering only errors to a separate alerting system.

‍

Step 2 — Configure filters

By default, a log drain forwards all log levels from all functions. You can narrow the scope using filters:

# Forward only error-level logs
vertex drain create \
  --name "errors-only" \
  --url https://alerts.example.com/ingest \
  --level error

# Forward logs from a specific function only
vertex drain create \
  --name "auth-logs" \
  --url https://ingest.example.com/logs \
  --function auth-handler

Available log levels are debug, info, warn, and error. Specifying a level will forward that level and all levels above it in severity.

Events not arriving at the endpoint

If test events are not reaching your endpoint, check the following:

1. Confirm the destination URL is publicly accessible and not behind a firewall or VPN
2. Make sure your endpoint responds with a2xxstatus code — redirects (3xx) are not followed
3. Check the drain's Activity log in the dashboard for delivery attempts and error messages
4. Runvertex drain status my-log-drainto see the current health of the drain

‍

Signature verification failing

If your endpoint is rejecting events due to signature mismatch, verify the following:

• You are computing the HMAC over theraw request body bytes, not a parsed JSON object
• The signing secret matches exactly what was set with--secretwhen the drain was created
• You are comparing the full string including thesha256=prefix

To rotate the signing secret without recreating the drain:

vertex drain update my-log-drain \
  --secret new-signing-secret

‍

High volume causing endpoint timeouts

During traffic spikes, your endpoint may receive a high volume of batched requests. If it starts timing out, consider the following:

• Respond with202 Acceptedimmediately and process events asynchronously in a background queue
• Use the--level warnor--level errorfilter to reduce volume on high-traffic projects
• Contact support to increase the batch window or request a dedicated drain throughput allocation