Puck docs

Getting started: Linux host ​

Install a Host Collector on a Linux Host, using the config the app generates for a Source, and ship its logs to Puck. The config reads the text logs in /var/log and every Docker container, with container names and labels, and keeps a queue on disk so an outage or a restart loses nothing.

You need a Source and its credential first: see Getting started.

Install and run ​

  1. Install otelcol-contrib 0.161.0 on the Host. The config is written for that version.

  2. On the Sources page, open your Source and choose Download collector config. The file is called obs-source-<slug>.yaml, for example obs-source-api.yaml. It holds no secret.

  3. Set both variables for the Collector from your secret store. For a Source called api:

    sh
    export OBS_SOURCE_API_CREDENTIAL_ID=<the credential ID>
export OBS_SOURCE_API_SECRET=<the secret>

  4. Run it:

    sh
    otelcol-contrib --config obs-source-api.yaml

To run it as a service, put the same two variables in the service's environment instead. With systemd that is an Environment= or EnvironmentFile= line in a drop-in for the otelcol-contrib unit, and the config file goes where the unit's --config points.

Reading /var/log needs read access to its files. Reading containers needs access to the Docker socket.

One config per Host ​

The config sends all of a Host's logs to its Source. Don't run two downloaded configs on one Host, or every Log record is sent twice.

A container's Service is its resource.opentelemetry.io/service.name label, else its Compose or Kamal service, else its name without a trailing version.

Check that it works ​

The Sources page shows "Waiting for logs…" until the first Log record arrives, then "Receiving logs" with the time it last saw one. Then open Explore and search with the Filter source:api. If nothing arrives within a minute or two, see Troubleshooting.

With Ansible ​

If you manage Hosts with Ansible, the osethinc.obs collection has a host_collector role. It installs otelcol-contrib as a systemd service and renders the same config the app does, so you don't download it. You create the Source and its credential in the app first, then give the role the credential.

yaml
- name: Ship logs to Puck
  hosts: db
  become: true
  roles:
    - role: osethinc.obs.host_collector
      vars:
        obs_endpoint: https://ingest.usepuck.eu:4318
        obs_sources:
          - slug: api
            credential_id: "{{ obs_secrets.api.credential_id }}"
            secret: "{{ obs_secrets.api.secret }}"
            varlog: true
            containers: all

Keep the credential in your own secret store (Ansible Vault, SOPS, 1Password) and pass it in; the role never looks it up itself. Leave out obs_ca_cert: Puck's certificate chains to a public authority. The collection is installed from Git at a pinned ref and is not on Ansible Galaxy yet. Write to us for access and the ref to pin.