Log Drains

Log Drains automatically forward your application logs to an external destination in real time. Use the built-in Datadog integration or send NDJSON payloads to a custom HTTPS webhook.

Setting Up a Log Drain

Go to Dashboard > Log Drains
Click Create Log Drain
Choose a destination and configure it:

Datadog
Webhook

Name — A label for this drain (for example, “Production logs”)
Site — The Datadog site for your organization
API Key — A 32-character Datadog API key
Service — The service name attached to each log (default: fal-log-drain)
Source — The source attached to each log (default: fal)
Tags — Optional comma-separated Datadog tags (for example, env:production,team:inference)
Sampling Rate — Maximum logs per delivery batch (1-5000, default: 1000)

fal stores the API key as a credential and sends it in the DD-API-KEY header. Never put an API key in an endpoint URL.

Click Test to verify connectivity before saving

Log Drains require Admin role in your team. Only one log drain can be active per account.

Log Format

Webhook logs are delivered as NDJSON (newline-delimited JSON) via HTTP POST. Each line is a JSON object:

{"timestamp": "2026-02-17T10:30:00.123Z", "message": "Model loaded successfully", "level": "info", "fal_app_name": "my-model", "fal_app_id": "abc123", "fal_request_id": "req-456", "fal_job_id": "job-789", "fal_endpoint": "/", "fal_node_id": "node-1", "fal_worker_id": "worker-42"}
{"timestamp": "2026-02-17T10:30:01.456Z", "message": "Inference completed in 1.2s", "level": "info", "fal_app_name": "my-model", "fal_app_id": "abc123", "fal_request_id": "req-456", "fal_job_id": "job-789", "fal_endpoint": "/", "fal_node_id": "node-1", "fal_worker_id": "worker-42"}

Fields

Every log line contains the core fields plus any available context labels. Fields beyond timestamp, message, and level are included only when the platform has a value for them.

Field	Description
`timestamp`	ISO 8601 timestamp
`message`	The log message
`level`	Log level (`info`, `warning`, `error`, etc.)
`fal_app_name`	Your application name
`fal_app_id`	Application identifier
`fal_request_id`	The request that generated this log
`fal_job_id`	The fal-internal job identifier for the runner
`fal_endpoint`	The endpoint path that handled the request (e.g., `/`)
`fal_node_id`	The unique ID of the infrastructure node the runner is on
`fal_worker_id`	The scheduler-level allocation ID for the runner
`fal_source`	Log source (e.g., `run`, `gateway`)
`fal_isolate_source`	Runtime-level log source

The Datadog integration sends the same fields through Datadog’s Logs API as JSON batches. It also adds the configured service, ddsource, and ddtags values and maps platform log levels to Datadog’s status field.

Verifying Webhook Signatures

Every webhook delivery includes an X-Fal-Signature header containing an HMAC-SHA256 signature of the request body, signed with your secret token. Use this to verify that deliveries are genuinely from fal.

import hmac
import hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Webhook deliveries use the Content-Type: application/x-ndjson header. Datadog deliveries use Content-Type: application/json.

Delivery Behavior

Logs are delivered in batches on a regular schedule
New drains start delivering logs from the last 30 seconds
The sampling rate controls the maximum number of log lines per batch
Deliveries time out after 10 seconds

Failure Handling

If your destination returns an error or is unreachable:

fal tracks consecutive failures
After 5 consecutive failures, the drain is automatically disabled
You can re-enable it from the dashboard after fixing the endpoint
The dashboard shows the failure count and last successful delivery time

Managing Log Drains

Manage your drain from the Dashboard. You can enable or disable it, test connectivity, update its destination settings or sampling rate, or delete it entirely. For a custom webhook, use an HTTPS endpoint you control that accepts NDJSON over HTTP POST. Keep credentials out of the endpoint URL; authenticate requests by verifying the X-Fal-Signature header instead.

Observability Overview

See all monitoring interfaces: dashboard, CLI, and integrations

Setting Up

Model APIs

Serverless

Compute

Organizations

Log Drains

Setting Up a Log Drain

Log Format

Fields

Verifying Webhook Signatures

Delivery Behavior

Failure Handling

Managing Log Drains

Observability Overview

​Setting Up a Log Drain

​Log Format

​Fields

​Verifying Webhook Signatures

​Delivery Behavior

​Failure Handling

​Managing Log Drains

Observability Overview

Setting Up a Log Drain

Log Format

Fields

Verifying Webhook Signatures

Delivery Behavior

Failure Handling

Managing Log Drains