Connecting Loki to Landfall

Connect your own Grafana Loki so Beacon and every agent in the war room can read its logs during an incident. A metric shows that something broke; the log line often shows why, with a stack trace, an error message or a request id.

• As a source: Beacon and joined agents discover your labels and run LogQL. It takes a base URL, a tenant ID if your Loki runs multi-tenant, and a bearer token or a basic auth username and password if it sits behind auth.
• As a trigger: a rule in Loki's ruler opens a war room through Alertmanager, which authenticates with a per-organization webhook secret. See Opening a war room from a Loki ruler alert.

What you'll need

• A Loki server Landfall can reach. A Loki inside your own private network is usually not reachable from a hosted Landfall the way a public SaaS API is.
• Its tenant ID if it runs multi-tenant, the common case for a Loki you run yourself. Landfall sends it as X-Scope-OrgID on every request. A single-tenant Loki running with auth_enabled: false needs none.
• An admin on your Landfall organization. Only admins can list, test and save connections.

1. Check Loki on its own side

The quickest check is Loki's own API, from a machine on the same network as the server. There is no key or account to create in Loki.

1. curl /loki/api/v1/labels

   TerminalCopy

   curl -s https://loki.example.com/loki/api/v1/labels \
     -H "X-Scope-OrgID: acme"   # only for a multi-tenant Loki

   A working Loki answers {"status":"success","data":["app","level","namespace"]}, listing the label names it has ingested. An empty data list means Loki has no recent logs for that tenant. Fix that before you connect Landfall.

2. Add it to Landfall

1. Integrations → Context sources → Loki

   Choose Integrations in the left menu, then the Loki tile under Context sources. Enter your server's base URL, and the tenant ID if it runs multi-tenant. Add a bearer token, or a basic auth username and password, only if your Loki needs one. When both are set, the bearer token is used.

   app.landfalls.ai · Integrations · Loki

   

2. Test connection

   Landfall calls your server's /loki/api/v1/labels with the tenant ID and credentials you entered, and saves nothing. It does not use /ready, which answers before Loki checks the tenant or auth at all. A good answer prints Loki reachable at https://loki.example.com, with your own base URL.

   app.landfalls.ai · Integrations · Loki

   

3. Save integration

   Save checks the server again before it stores anything. A Loki that cannot be reached, or that rejects the tenant ID or credentials, is refused and nothing is stored. Once saved, the Loki tile reads Configured.

   app.landfalls.ai · Integrations · Loki

   

What it looks like

When Beacon or an agent runs queryRange over the incident's window, Landfall flattens Loki's streams into log entries, each with its stream's labels. That is the shape a Log view widget shows, so the lines can sit on the war room's canvas next to the conversation.

What Beacon can read

Every answer reaches the agent as Loki's own JSON, unchanged. These operations reach Beacon and every agent that joins the war room through get_signal_catalog and query_signals. See Integrations architecture.

Opening incidents from Loki

A rule in Loki's bundled ruler can open a war room by itself. The ruler notifies Alertmanager, and Alertmanager calls Landfall through a webhook that carries your organization's secret. The setup has its own page, Opening a war room from a Loki ruler alert. Reading logs and opening incidents are independent, so you can set up either one alone.

Troubleshooting

Reference