Netlify Logs

Stream serverless function logs from Netlify into Gonzo for real-time analysis, filtering, and AI-powered insights.

Stream function logs into Gonzo with a lightweight jq normalizer. Netlify's CLI doesn't have a --json flag for function logs — it outputs LEVEL MESSAGE text over WebSocket. The normalizer splits the level, promotes any embedded JSON fields, and drops blank lines so Gonzo receives clean JSONL.

Quick Start

netlify login
netlify link
netlify logs:function <function-name> \
  | jq --unbuffered -R '
    select(length > 0) |
    (index(" ")) as $i |
    if $i then
      {level: .[:$i] | ascii_downcase, message: .[($i+1):]}
    else
      {level: "info", message: .}
    end |
    (.message | fromjson? // null) as $json |
    if $json then . + $json else . end |
    select(.message | length > 0)
  ' \
  | gonzo

Replace <function-name> with your function (e.g. hello, submit-form). The --unbuffered flag on jq is required — without it, output buffers and logs stall.

Prerequisites

• Gonzo installed

• Netlify CLI installed (npm install -g netlify-cli)

• jq installed (brew install jq)

• A Netlify project with at least one deployed serverless function

Log Types

Log type	CLI access	Gonzo compatible	What it captures
Function logs	logs:function <name>	✅ Yes (with normalizer)	console.log/warn/error output + platform invocation metrics
Deploy logs	logs:deploy	⚠️ Limited (plain text)	Build output during git-triggered deploys
Edge Functions	Dashboard only	❌ Not via CLI	Deno-based edge function console output
Traffic logs	Enterprise Log Drains	❌ Not via CLI	CDN request logs: method, path, status, duration

Usage Patterns

Stream a specific function:

netlify logs:function hello | jq --unbuffered -R '<normalizer>' | gonzo

Filter by level at the source:

netlify logs:function hello --level warn error | jq --unbuffered -R '<normalizer>' | gonzo

Watch a deploy in real time (plain text, no structured fields):

netlify logs:deploy | gonzo

Capture to file for replay:

netlify logs:function hello | jq --unbuffered -R '<normalizer>' > /tmp/netlify-logs.jsonl &
gonzo -f /tmp/netlify-logs.jsonl --follow

With local AI (logs never leave your machine):

export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"
netlify logs:function hello | jq --unbuffered -R '<normalizer>' | gonzo

Multiple Functions

The Netlify CLI streams one function at a time — there is no "stream all" mode. To monitor multiple functions, run separate terminal sessions each piping a different function into Gonzo.

Platform Latency

Function logs typically appear in the CLI stream 5–15 seconds after execution. This delay is inherent to Netlify's log delivery and is not affected by the Gonzo pipe or the jq normalizer.

Structured Logging Tips

Netlify does not add timestamps to function log output. For the best Gonzo experience, emit structured JSON with at least message, level, and a timestamp:

console.log(JSON.stringify({
  message: "User signup completed",
  level: "info",
  ts: new Date().toISOString(),
  userId: 123
}));

The normalizer automatically promotes these fields to the top level, giving Gonzo access to timestamps and custom fields for filtering.

Avoid pretty-printed JSON — JSON.stringify(obj, null, 2) spans multiple lines and each line becomes a separate log entry. Always use minified: JSON.stringify(obj).

Troubleshooting

Symptom	Cause & fix
"No site linked"	Run netlify link to connect your terminal session to a project.
Function returns 404	Verify with netlify functions:list. Check [functions] directory in netlify.toml.
Logs appear empty	Function may not have been invoked. Trigger the endpoint and wait 5–15s for delivery.
jq hangs / no output	Missing --unbuffered on jq. Without it, output buffers when writing to a pipe.
Blank JSON lines in output	Ensure the full normalizer with select(length > 0) and select(.message | length > 0) is included.
logs:deploy says "No active builds"	Deploy logs only attach to remote builds (git push / Netlify UI). CLI deploys build locally — no remote stream.

---

Time to complete: 5 minutes Prerequisites: Netlify CLI, jq, Gonzo installed Full guide: guides/NETLIFY_USAGE_GUIDE.md