logs

View redacted approved diagnostic logs

Install

docsloth component add @docsloth/logs@1.0.0

Live package: sha256:ab7d4448c13820a9f6a9a6d8fa00cd07a37884dd142754f531cb34fbd78fb9c7 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/logs.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  },
  "query_template_id": "example-query_template_id",
  "max_rows": 1,
  "redaction_profile": "example-redaction_profile"
}

Required props: resource, query_template_id, max_rows, redaction_profile.

Example

Example document IR (the block the renderer consumes):

{
  "type": "logs",
  "props": {
    "title": "example-title",
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    },
    "query_template_id": "example-query_template_id",
    "max_rows": 1,
    "redaction_profile": "example-redaction_profile"
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-logs" data-component="logs" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<dl class="ds-facts">
<div>
<dt>Query</dt>
<dd>
<code>example-query_template_id</code>
</dd>
</div>
<div>
<dt>Row limit</dt>
<dd>1</dd>
</div>
<div>
<dt>Redaction profile</dt>
<dd>
<code>example-redaction_profile</code>
</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Querying logs needs the live documentation site.</p>
</section>

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/logs.md.

Contract

Production props are normative in ../contracts/component-props/logs.schema.json. The corresponding component-fixtures manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated component-package.json manifest plus props.schema.json (the production props schema, copied byte-for-byte) and spec.md (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

Intended behavior

Approved parameterized log queries only; no general SQL or unrestricted production log access.

Failure and fallback

Timeout exposes redacted error; log lines treated as untrusted text.

The React component resolves ComponentContentProvider.logQueries using logQueryKey(resource, query_template_id, redaction_profile, max_rows). An available adapter is pinned to the release, actor session, query version and all key fields. It may supply a redacted snapshot and an explicit query action; no query runs during rendering, hydration or local level filtering. General SQL, arbitrary query strings and legacy inline lines props are not accepted.

The host authorizes and budgets each query, enforces the approved template and row limit, and applies its redaction profile before sending data to the client. Snapshots must identify the complete scope, capture time, immutable snapshot ID, truncation and applied redaction. The client admits at most the requested 1–500 rows, 4,096 UTF-16 code units per message and 131,072 total code units of row identifiers/messages. Identifiers are bounded and unique, severity is typed, and timestamp dates/times must be valid and explicitly zoned. Extra response fields are discarded. Host serialization and transport need independent byte limits; these in-memory checks do not bound an untrusted network response.

Common credential, email and IP patterns are additionally masked for display, and markup is rendered as text. This is not complete PII detection and cannot protect data already delivered. Failed queries show a fixed public-safe error, never raw server details. Denial or malformed results clear prior rows. Stop waiting aborts the adapter signal and discards late replies, without claiming server cancellation. Scope and supplied snapshot changes reset displayed data. No browser persistence, polling, model or executor dispatch occurs. Production core/cloud transport and server protections remain host integration work.

Required acceptance cases

Stored XSS and PII token fixtures never rendered raw. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

Package manifest

Protocol fixture: packages/contracts/component-fixtures/logs.json.

Sources