Why does a runbook attached as a reference document still appear outside the time window?

Tares always surfaces a runbook attached as a reference document when you read its entity, because reference documents are declarative material, not a stream. A read time window filters events by time, and a reference document is exempt from that filter. Read the entity, for example service tares, and the runbook comes back in the timeline even when the window is only 15 minutes.

How it works

The reference source type is different from the event connectors. Event connectors poll or receive a stream, and each event has a time that decides whether it falls inside a read window. A reference source is not polled or pushed. You declare it, and Tares keeps it as reference material for the entity it describes.

Here is what that means in practice:

• The config is the data. Each entry under attachments carries its own name, content, optional format (json, csv, md or txt) and labels.
• Each document becomes one always-surfaced event. Tares materializes every attachment into a single event that is returned whenever you correlate on a matching entity.
• Labels do the matching. The labels you tag a document with, such as service=tares and environment=production, become real Tares labels. A read on those labels finds the document. There is no entity key, because correlation is label-native.
• The time window does not apply. A runbook does not age out of a 15-minute read, because the document is surfaced regardless of the read time window.
• There is no poll interval. Editing the source re-materializes it, so changes to a runbook show up after you save the source.

This is why the runbook shows up next to live events when you read the entity. You get the fresh signal from your event sources and the standing instructions for that entity in one result. The AI SRE guide shows where that fits in a wider monitoring setup.

Set it up

1. Open Sources → Add source → Reference documents.
2. Upload your json, csv, md or txt files. Tares reads them into text.
3. Tag each document with the labels of the entity it describes, for example service=tares and environment=production.
4. Click Create. To add more documents later, re-open the source and use Upload more.

If you prefer config, declare the same source in YAML. The labels list at the bottom declares the label names so reads can correlate on them, and each attachment supplies 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 }

You can also send the same object with POST /api/sources.

To verify the behavior, check the source and then read the entity:

5. Open the source. Recent events shows one event per document, and Fields shows the labels they carry.
6. Read the entity the documents describe, using a short window if you like.

read({ service: tares })

The runbook documents come back in the timeline, even though they fall outside the read window. The full field list is on the Reference documents page.

What you get

• Runbooks that never age out. A restart procedure, a schema or project notes appear on every read of the entity, whatever window you choose.
• Context next to live events. When you or an agent correlate on an entity, the standing documents arrive in the same timeline as the recent events.
• Labels you can use. The labels on each document become real Tares labels, so you can read on them and trigger on them like any other label.
• Simple maintenance. Editing the source re-materializes it. There is no schedule to tune and no entity key to manage.
• A quick check. One read of the entity, such as read({ service: tares }) in the text block above, confirms the document is attached and surfaced.

When something else fits

• If the data changes over time and you want it limited to a window, such as metrics, logs or alerts, use an event connector instead. Those are streams, and the read time window applies to them.
• If a document is not tied to an entity, a reference source is the wrong fit, because it is attached by labels and surfaced only when you correlate on a matching entity.
• If you need a document to drop out of results after a while, remove it from the source. Reference documents stay surfaced for as long as they are attached.

Related