Remote source

Connect a telemetry service you host yourself, in any language, as a source Beacon, the diagnosis agent, reads from during an incident. The service speaks the Landfall Source Protocol over HTTP or gRPC; Landfall connects to it by base URL, the same way it connects to Prometheus or Loki, and from then on treats it like every other source.

What a remote source is

Every bundled source (Datadog, CloudWatch, Prometheus, Loki, and the rest) is a package Landfall ships. A remote source is the same contract turned inside out: instead of Landfall holding the vendor client, you run a small service that answers seven calls, and Landfall asks it what it can do. Landfall never needs a code change to reach a system it has never heard of; the service's own capabilities listing is what the investigator reads.

The protocol is deliberately small: a capabilities listing, a health check, a raw invoke for any operation the service advertises, and canonical list-and-range calls for metrics and for logs. The full wire contract, the reference server, and the conformance suite are on the Source SDK reference; the design behind it is on Data sources architecture.

What you'll need

• A service implementing the Source Protocol, reachable from Landfall. A service inside your private network is typically not reachable from a hosted Landfall the way a public API is, the same limitation documented for Prometheus and Loki.
• Either a bearer token the service will accept, or, for mutual TLS, a client certificate and key the service trusts. One credential per connection.
• An admin on your Landfall organization, to save the connection under Settings → Integrations.

Nothing to try yet? Start with the reference server that ships with the SDK. It serves a fake metrics and logs store over both transports and accepts the token dev-token:

node dist/libs/signals/protocol/reference-server.js --http 8787 --grpc 8788

Confirm it answers before connecting Landfall to it. A working service returns its capabilities listing, the same document Landfall will read on Test connection:

curl -s -H "Authorization: Bearer dev-token" http://localhost:8787/v1/capabilities

Connecting a remote source

1. Settings → Integrations → Remote source

   Enter the service's base URL (the origin only; Landfall appends /v1/… itself), choose the transport the service speaks (HTTP or gRPC), and supply the credential: a bearer token, or a client certificate and key for mutual TLS. Give the connection a label if you plan to connect more than one service; the label is what the investigator sees.

   Settings → Integrations → Remote source

   

2. Test connection

   Landfall calls the service's /v1/health and then /v1/capabilities with the credential you supplied, before saving anything. A service that cannot be reached, rejects the credential, reports ok: false, or announces a protocol version Landfall does not speak is refused outright rather than stored as "configured but unverified." On success the panel shows what the service declared: its name, its kinds (metrics, logs, or both) and every operation it advertises.

   Settings → Integrations → Remote source

   

3. Save integration

   The connection now shows Configured alongside your organization's other connectors. The capabilities captured at verification are stored with the connection and refreshed on every later health check, so a service that gains an operation is picked up the next time the connection is checked, and a query against an operation the service no longer lists is refused before any network call.

What Beacon sees once it is connected

A connected remote source appears in the signal catalog under the source tag remote, with your connection's label, its kinds, and its own operations, each tagged with the kind of data it reads. The investigator's discovery tools reach it through the canonical calls (list what metrics exist, read a metric over the incident's window, list log streams, read log entries), so there is zero source-specific agent code: the same dynamic-discovery mechanism every bundled source uses (see Integrations architecture).

Every read passes through the same guardrails as a bundled source: the incident-scoped grant, tenant scoping, connection resolution, the audit trail and the timeout budget. The provider's raw payload is returned verbatim in the standard result envelope; if the service also returns a shaped series or entries field, canvas widgets use that shape directly, and fall back to the raw payload when it is absent. A service that is unreachable or errors produces a partial result with the reason, never a silent empty.

Agents that join the war room from a terminal or from the hosted manager connector see the same catalog through get_signal_catalog and read from it through query_signals, under their own grant.

Opening an incident from your service

Connecting a remote source (above) lets the investigator read from it. Opening an incident automatically from the service's own alerting is a separate, independent capability with its own guide: see Triggering Integrations → Remote source. The two are independent; most teams eventually set up both.

Reference