How do I tell an AI SRE that 5xx errors on an API is a known issue with a documented fix?

Tares lets you attach your runbook for 5xx errors on an API to the API’s entity as a reference document. A reference document is declarative reference material, not a stream, so Tares always surfaces it when correlating on that entity, whatever the read time window. The fix stays in front of the AI SRE even when the errors are hours old.

How it works

The reference connector turns documents into entity knowledge. It accepts json, csv, md and txt files, such as project notes, schemas and runbooks. You tag each document with the labels of the entity it describes, for example service and environment.

• Always surfaced. Event connectors produce streams that a read window cuts off. A reference document does not age out. A runbook is not dropped from a 15-minute read.
• One event per document. Each attachment is materialized into one always-surfaced event.
• Label-native. There is no poll interval and no entity key. Correlation works on the labels, and the labels you tag each document with become real Tares labels you can read and trigger on.
• The config is the data. Each attachment carries its own name, format, content and labels. Editing the source re-materializes it.

For 5xx errors on your API, the entity is the API itself. Tag the runbook with that API’s labels, and the documented fix comes back whenever the AI SRE reads that entity. The AI SRE guide covers how Tares investigates an entity. The reference documents connector page covers the source type in full.

Set it up

1. Write the fix as a short md or txt file. Name the symptom, 5xx errors on the API, and give the documented steps to resolve it.
2. In Tares, go to Sources → Add source → Reference documents.
3. Upload the file. Tares reads it into text.
4. Tag the document with the labels of the entity it describes, such as service and environment. Use the same labels your API’s other sources carry, so the runbook correlates on the same entity.
5. Click Create. To add more documents later, re-open the source and use Upload more.

You can also define the source as YAML, or send the same object with POST /api/sources. The labels block declares the label names so reads can correlate on them. Each attachment provides the values.

- 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 }

Replace the name, the content and the label values with your own. Use the file name and text of your 5xx runbook and the labels of your API.

To verify, open the source. Recent events shows one event per document, and Fields shows the labels they carry. Then read the entity the document describes by its labels. The document comes back in the timeline, even outside the read window.

What you get

• The documented fix for 5xx errors on your API is attached to the API’s entity and always returned when Tares correlates on that entity.
• The runbook does not drop out of a short read window, so the AI SRE sees it however old the errors are.
• The labels on the document are real Tares labels. You can read on them and trigger on them.
• One place to maintain the runbook. Edit the source or upload more documents, and Tares re-materializes it.
• Several documents on the same entity work together. Add the restart steps, the rollback notes and a schema next to the 5xx fix, each tagged with the same labels.

When something else fits

• If you want Tares to watch for 5xx errors as they happen, use an event connector for the API, such as the webhook, OTLP or docker logs connectors. A reference document holds the fix, not the errors.
• If the knowledge is a one-off observation from an agent rather than a maintained runbook, the memory connector is the better fit.

Related