How do I let an AI SRE look at JSON API endpoints when investigating slow database queries?

Tares polls any JSON API endpoint with an http_poll source, so you can add business data such as affected customers next to the telemetry for a slow query. Give the source a label that matches your telemetry’s service label, and the two share an entity.

How it works

The http_poll connector calls your endpoint on the source’s schedule and stores one event per item in the reply. An object is one event and a list is one event per entry. The payload is stored as received, so labels you declare later can still reach every field, dotted names such as customer.plan included.

• payload_key points at the part of the reply that holds the items, for example data.items. Empty means the entire JSON.
• id_field is the deduplication key. An item whose value was seen in recent polls is not stored again.
• event_time_field names the field with the event’s time. Empty means the poll time.
• text_template sets the one-line summary of each event.

One rule decides whether this data meets your telemetry. Tares puts two sources on the same entity only when they carry a label with the same name and the same value. Polled items do not join your logs, metrics or traces just because they exist. For example, an OTLP source carries the service in resourceAttributes.service.name. To line an endpoint up with it, give the http_poll source a label named service with the same value, such as checkout.

The same rule applies to rows. The Postgres connector reads a table incrementally on a cursor column, one event per new or changed row, and a primary label such as tenant_id becomes the entity key. A Postgres source keyed on tenant_id does not meet an OTLP source keyed on service unless you add a shared label to both.

For the wider picture of how an investigation uses this data, see AI SRE.

Set it up

1. Pick the endpoint that shows who is affected, for example an orders or sessions API of your own. If you want table rows instead, use the Postgres connector.
2. Ask a connected agent to set it up, or go to Sources → Add source → HTTP API (poll). Fill in the method, the URL, and any credential or headers, then press Discover. Tares calls the API once, shows the reply, and proposes what becomes an event.
3. If the API needs a credential, put the whole value in credential and name the header in credential_header. Tares stores the credential as a secret and never returns it through the API. Other headers go in headers.
4. Add a label that matches your telemetry. Name it service and give it the same value your OTLP source carries in resourceAttributes.service.name.
5. Set a poll interval of 10 seconds or more. The connector refuses anything shorter when you save.

- name: checkout_orders
  connector: http_poll
  poll: 1m
  config:
    url: https://api.example.com/v1/orders
    payload_key: data.items
    event_type: order
    id_field: id
    text_template: 'order {id} {status}'
    labels:
      - { name: service, const: checkout, primary: true }
      - { name: status, field: status }

6. For a Postgres source, add a label named service with the same value in the same way, next to the tenant_id label.
7. Open the source. Recent events shows each poll’s events with the summary line, and Fields lists every field seen with its coverage. Check that the service label is present on every event.

You can also create the source with POST /api/sources and the same object.

What you get

• Business events from your own API, such as orders, sessions or errors per customer, stored in Tares as they change.
• A service label on those events that matches the label on your telemetry, so both sit on the same entity.
• No duplicate events when the API returns the same item on every poll, because id_field deduplicates.
• Number labels you can use in triggers. For example, a trigger can watch a count or a maximum over a window of your choice.
• Built-in handling of API limits. On a 429 or any 5xx the connector backs off, doubling the wait up to an hour and honoring Retry-After. The source’s health shows when the next try is. Other 4xx replies appear as a config error with the status and part of the reply.

When something else fits

• Use the Postgres connector when the data you need is a table in your own database and you want a cursor on an id or updated_at column instead of an API.
• Use the webhook connector when the system can call Tares itself, rather than being polled.
• If your telemetry and your business data carry no label in common, add one before expecting them to share an entity.

Related