Skip to content
WatchTower15Docs

Log sources

A log source is anything that sends log lines to WatchTower15 without running the agent: an AWS Lambda, a CI job, an edge function, a container, a script. It is a first-class thing in its own right — it has an identity, an ingest credential, tags, health and its own place in log search — and it is billed exactly like agent logs, per GB of content.

Use a log source when the thing producing the logs is not a machine you can put an agent on. If it is a server you control, enrol the agent instead: it handles batching, offsets, rotation and back-off for you.

Sources and streams

Section titled “Sources and streams”

Two words that are easy to mix up, and worth getting straight before you start:

Term Means Examples
Source Who sent the line web-01 (a server), aws-ssm-summary (a log source)
Stream What within it produced the line nginx-error.log, journald, aws.cloudtrail

Every log line carries both. A server tails many files, so one source has many streams. A log source that just posts one kind of line has exactly one — and if you do not set a stream name, WatchTower15 uses the source’s slug, so it still appears in the Stream filter and can be isolated like any other.

Creating one

Section titled “Creating one”

Log Sources → Add. You need the log_sources.edit permission (Admin and Operations Lead have it by default).

  • Name — what you will see in the log viewer. Editable later.
  • Slug — derived from the name, editable only while creating. It becomes the default stream name, and stream names are part of how lines are stored, so changing it later would split the source’s history in two rather than rename it. Pick something you are happy to live with.
  • Silence thresholds — how long without a line before the source is flagged. Defaults are 15 minutes (warning) and 60 minutes (critical).

Saving mints an ingest token and shows it once.

The token

Section titled “The token”

The token is the identity — there is no source id or slug on the wire, just the bearer header. It is shown exactly once, on creation or rotation, because only a SHA-256 hash of it is stored. If you lose it, rotate for a new one; it cannot be recovered.

Action Effect
Rotate Issues a new token and invalidates the old one immediately. There is no overlap window, so rotate and then redeploy the publisher.
Revoke Stops the source accepting lines. It keeps its identity, tags and history, and you can issue a new token whenever you like.
Pause (Ingestion active off) Same effect on ingest, but framed as a state rather than a credential problem.
Delete Refuses further pushes and removes the source. Its existing log lines stay searchable for the rest of the retention window — see below.

Treat it as a production secret: anyone holding it can write log lines into your organisation and run up ingest charges. Store it in a secrets manager, not in source control.

Sending lines

Section titled “Sending lines”

See the log ingest API for the full contract. The short version:

Terminal window
curl -X POST https://api.watchtower15.com/api/log-sources/ingest \
  -H "Authorization: Bearer wt15ls_…" \
  -H "Content-Type: application/json" \
  -d '[{"message":"SSM summary: 3 instances patched"}]'

No SDK, no gzip, no signing.

Health

Section titled “Health”

A log source’s health comes from one question: how long since we last heard from it?

State Meaning
Awaiting first log line Created but has never sent anything. Deliberately never alarms — a provisioned-but-not-yet-wired source should not page anyone.
Healthy A line arrived within the warning threshold.
Warning / Critical Silent beyond the configured thresholds.

A source that went quiet returns to Healthy when its No logs received incident resolves — on the next evaluation pass after a line arrives, within a minute — rather than the instant the line lands.

The first line a source ever sends is recorded on its Audit tab as First data received, together with its move from Awaiting first log line to Healthy. Every later health change is recorded there as Health changed.

One honest caveat: “last received” means we accepted a batch, not the lines are searchable yet. If our forwarder stalls, the source still looks healthy — that is a platform problem with its own alerting, not yours.

Billing and retention

Section titled “Billing and retention”

Log-source volume is billed per GB of log content, at the same rate as agent-shipped logs, and appears on the invoice under Log sources with the source named. The searchable window is 30 days, the same as everything else.

Deleting a source does not delete its log lines. They remain searchable until they age out of the retention window, and the viewer keeps showing the source’s name against them, marked (deleted).

Section titled “Related”