What is the difference between poll, push and reference connector modes?

Tares connectors run in one of three modes. With poll, taresd fetches from the upstream every poll interval, such as 5s or 1m. With push, your producers send events over HTTP to a generated ingest endpoint. With reference, the config is the data, and it is always surfaced. Pick the mode by who starts the conversation: Tares, your system, or nobody.

How it works

Every connector defines how a source gets events into Tares, and each one has exactly one mode. The connectors index lists the mode of each connector.

• Poll: taresd fetches from the upstream every poll interval, for example 5s or 1m. Prometheus, Prometheus alerts, Docker logs, Postgres, the HTTP API connector, Linear and GitHub Issues are poll connectors. GitHub is poll when you use a personal token.
• Push: producers send events to taresd over HTTP. A push source has a generated ingest_key, and producers POST JSON or NDJSON to the ingest URL for that key. Alertmanager, Vercel, Claude Code, webhook, memory and GitHub through the GitHub App are push connectors. OTLP is push too, but it uses the standard OTLP paths for logs, traces and metrics instead of the ingest key path.
• Reference: declarative, neither polled nor pushed. The config is the data, meaning documents attached to entities. Tares re-materializes it when you edit it, and always surfaces it regardless of the read window. The reference connector is the one reference-mode connector.

The push URL has this shape, and the OTLP endpoint uses the OTLP/HTTP paths:

curl -X POST http://localhost:8787/ingest/<ingest_key> \
  -H 'Content-Type: application/json' \
  -d '{"action": "deploy", "sender": "ci", "pipeline": "web"}'
 
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8787   # OTLP/HTTP → /v1/{logs,traces,metrics}

Set it up

Every connector can be set up three ways, and all of them normalize to the same stored config. You can ask a connected agent, which calls discover_source, test_source and create_source. You can use the console with Sources → Add source. Or you can declare the source as YAML in the catalog or with POST /api/sources.

1. Start Tares locally if it is not running yet:

   tares up

2. For a poll source, set the poll interval. Tares then fetches on that cadence:

   - name: logs
     connector: docker_logs
     poll: 5s
     config:
       container: tares-demo-api-server   # the container name (docker ps)
       labels:
         - { name: service, const: api-server, primary: true }

3. For a push source, leave out poll. Tares generates the ingest_key when you create the source, and your producer posts to that URL:

   - name: ci-events
     connector: webhook
     config:
       event_type_field: action
       text_template: '{action} by {sender}'
       labels:
         - { name: pipeline, field: pipeline, primary: true }

4. For a reference source, put the documents in the config. There is no interval and no producer:

   - name: runbooks
     connector: reference
     config:
       attachments:
         - name: restart.md
           format: md
           content: |
             1. kubectl rollout restart deploy/tares
             2. watch the pod come healthy
           labels: { service: tares, environment: production }
       labels:
         - { name: service, field: service }
         - { name: environment, field: environment }

5. Add a labels array to every source, whatever its mode. One entry is the primary label, which acts as the key. Some poll connectors also support discovery, so Tares can propose a config from partial input.

What you get

• You know where to look when data is missing. A poll source with no new events points at the upstream or the interval. A push source with none points at the producer or the ingest URL.
• Poll sources need no changes on the upstream side. Tares reaches out on your schedule.
• Push sources deliver events as your systems emit them, and any sender that can POST JSON or NDJSON works.
• Reference sources keep runbooks and similar documents next to the entity they describe. Edits take effect right away, and the documents show up when Tares correlates, however narrow the read window is.
• The same label model applies in all three modes, so triggers and agents treat events from any mode the same way. For how sources feed monitoring and triggers, see AI SRE.

When something else fits

• If your system is not in the list, use the HTTP API connector to poll any JSON endpoint. Use the webhook connector for anything that can POST, and OTLP for anything instrumented with OpenTelemetry.
• If you want history of what happened, use poll or push. Reference documents describe an entity and are not an event stream.
• GitHub supports both a push path (the GitHub App) and a poll path (a personal token), so choose by whether you want webhooks or an interval.

Related