# Clinic Log Identity And Detail Contract

Use this reference whenever a Clinic evidence plan includes `logs_range`.
It owns identifier interpretation for log acquisition only; it does not decide
causality, mechanism, severity, or handoff.

## Identifier shapes

Treat every ticket-supplied identifier as opaque until its shape and source
establish one of these contracts:

- A decimal value labelled connection ID, processlist ID, session ID, thread
  ID, or SQL ID is not a SQL Digest. Search the exact literal first. TiDB server
  logs commonly render the same value in a `conn` field, but the Evidence Agent
  must not require that spelling before the first lookup.
- A complete SQL Digest is exactly 64 hexadecimal characters. Use it as a
  `slow_query.digest` or `topsql.digest` only when the runner-owned context
  supplies it as a Digest or the ticket explicitly labels that complete value
  as a Digest or SQL ID. Shape takes precedence over the ambiguous SQL-ID
  label: a decimal SQL ID stays an opaque runtime identifier, while an exact
  64-hex SQL ID follows the SQL-Digest contract. Search component logs by the
  same exact literal only when log correlation is independently load-bearing.
- A 6-to-63-character hexadecimal Digest prefix is admissible only when a
  prior compact Provider handoff returned it as a Digest prefix. Do not promote
  an arbitrary short hexadecimal or decimal ticket value to a Digest.
- A plan Digest follows the same 64-hex exact and 6-to-63-hex prior-prefix
  shapes, but it must remain distinct from the SQL Digest.
- A value whose source or shape remains ambiguous stays an opaque literal. One
  exact-literal log lookup is preferable to parallel guessed connection,
  Digest, Statements, and table-text queries.

## LogQL construction

For an opaque identifier, start with one bounded literal query over the known
component and instance when present:

```logql
{container="tidb",instance="db-tidb-2"} |= "1571681454"
```

Omit `instance` only when the affected instance is genuinely unknown. Copy the
literal exactly and use `|=`; do not rewrite it as a regex, split it into
digits, prepend a guessed field name, or search only prose such as `SQL ID`.
The component, instance, and absolute time window remain the primary scope.

For error-class discovery without an exact identifier, use Clinic-compatible
backtick regex syntax, for example:

```logql
{container="tidb"} |~ `(?i)panic|fatal`
{container="tidb"} |~ `(?i)\[error\]`
```

Do not put escaped bracket regexes in double quotes.

## Detail choice

Every `logs_range` query selects `detailLevel` explicitly:

- `summary`: presence, count, time bounds, stream labels, and requested safe
  marker counts are enough to answer the neutral evidence question.
- `events`: the order, transition, duration, or state carried by matching log
  lines is load-bearing. Use this for delivery/acknowledgement/completion,
  kill/cancel lifecycle, shutdown correlation, repeated progress, or when the
  exact error event must be distinguished from a mere match count.

`events` returns bounded typed event kinds, counts, first/last timestamps,
source locations, booleans, numeric execution fields, and up to twenty
matching log lines. SQL, full Digests, connection IDs, addresses and ordinary
URLs remain available for internal diagnosis. Passwords, tokens, cookies and
other credentials are redacted before the result leaves the Provider.

The Evidence Agent chooses this acquisition detail but remains neutral. It
does not interpret an event sequence as the root cause. The Scenario Diagnostic
Agent receives the compact event facts and owns whether they establish signal
delivery, a cancellation-check gap, delayed cleanup, a wrong target, or another
mechanism.