← Volver al catálogo

Telemetry

Privacy-first local agent observability with a SQLite source of truth, bounded read-only query tools, and opt-in OpenTelemetry-aligned OTLP export

Detalles:

AnalíticaMantenido aquí

npmRepositorioSitioReportar un problema

Instalación

alisio install npm:@alisio/plugin-telemetry@0.1.1

Metadatos

Paquete	@alisio/plugin-telemetry
Versión	0.1.1
Publicado	4 oct 2026
Autor	Alisio
Licencia	MIT
Categorías	Analítica
Tamaño	303.9 kB
Dependencias	0
Peer dependencies	1
Descargas (último mes)	111
Origen	Primera parte
Palabras clave	alisio-plugin, telemetry, observability, analytics, opentelemetry, sqlite, tools

Nota de seguridad: Los plugins se ejecutan en proceso con tus privilegios de usuario y no están en un sandbox. Revisa el código fuente antes de instalar un plugin de terceros.

Privacy-first local agent observability for Alisio. It records what the agent does into a local SQLite database, exposes bounded read-only query tools, and can optionally export OpenTelemetry-aligned data over OTLP. Local-only is the default; remote export is opt-in.

This is an independent plugin. It is not affiliated with the OpenTelemetry project and claims no conformance to a stable semantic-convention release.

Install

alisio install npm:@alisio/plugin-telemetry

What it does

• Observes Alisio RunEvents through a synchronous, non-blocking handler and writes compact records to a local SQLite database.
• Serves five read-only tools that return bounded, aggregated, privacy-preserving summaries.
• Optionally exports traces, logs and metrics to an OTLP/HTTP endpoint with durable, idempotent batching.
• Ships a telemetry agent skill explaining when and how to consult it.

Privacy defaults

• Metadata-only by default. Prompt, completion, tool-argument and tool-result content capture is OFF unless explicitly enabled.
• Local-only by default. No network call is made until remote export is enabled with an endpoint.
• When content capture is enabled, every captured value passes through allowlist-based redaction: bearer/authorization headers, tokens, private keys, secrets in key/value form, absolute machine paths and (in strict mode) long high-entropy runs are stripped, and every field is bounded. Redaction is never denylist-only.
• The OTLP credential is never persisted, logged, returned or serialized. It is read at export time only, from the environment variable named by otlp.tokenEnv (default ALISIO_TELEMETRY_OTLP_TOKEN). The config file may only reference the variable's name.
• Telemetry can reveal how someone works, which repositories they use, and what they type. Keep strict redaction on, prefer metadata-only, and set a retention window you are comfortable with.

Configuration

Configuration precedence, highest first:

1. Explicit non-secret command/tool argument (for example /telemetry:telemetry-setup --retention-days 7).
2. Environment variables.
3. The config file at /telemetry/config.json.
4. Built-in safe defaults.

configHome resolves as ALISIO_CONFIG_HOME, else XDG_CONFIG_HOME/alisio, else ~/.config/alisio. stateHome resolves as ALISIO_STATE_HOME, else XDG_STATE_HOME/alisio, else ~/.local/state/alisio.

The database path is ALISIO_TELEMETRY_DB, else /telemetry/telemetry.sqlite. Telemetry stores its data through the host-provided SQLite storage port (api.storage.sqlite), so the plugin never depends on a runtime SQLite driver. Because the host port sets no pragmas, the plugin hardens the port right after opening: it enables WAL, a busy_timeout, foreign keys and NORMAL synchronous mode, ensures parent directories are 0700 and the database file is 0600, and periodically runs PRAGMA optimize.

An invalid configuration fails closed: telemetry is disabled and an actionable message is reported. It never crashes the host.

Settings

Field	Meaning
retentionDays	How long records are kept before telemetry-prune removes them
capture.prompts / .completions / .toolArguments / .toolResults	Opt-in content capture (redacted, bounded)
redaction.mode	strict (default) or standard
otlp.enabled	Master switch for remote export
otlp.endpoint	OTLP/HTTP base URL, e.g. https://collector.example.com:4318
otlp.headers	Non-secret headers only; secret-shaped headers are refused
otlp.tokenEnv	Name of the environment variable that holds the token
otlp.serviceName / .environment / .instanceId	Resource attributes
otlp.samplingRatio	Deterministic per-run sampling, 0–1
otlp.signals.traces / .logs / .metrics	Which signals to export
otlp.gzip	Gzip the request body
otlp.maxAttempts / .timeoutMs / .batchSize	Export bounds
batch.batchSize / .flushIntervalMs / .maxQueue	Local write bounds

Environment variables

ALISIO_TELEMETRY_DB, ALISIO_CONFIG_HOME, ALISIO_STATE_HOME, XDG_CONFIG_HOME, XDG_STATE_HOME, ALISIO_TELEMETRY_RETENTION_DAYS, ALISIO_TELEMETRY_OTLP_ENABLED, ALISIO_TELEMETRY_OTLP_ENDPOINT, ALISIO_TELEMETRY_OTLP_TOKEN_ENV, ALISIO_TELEMETRY_OTLP_INSTANCE_ID, ALISIO_TELEMETRY_SERVICE_NAME, ALISIO_TELEMETRY_ENVIRONMENT, ALISIO_TELEMETRY_SAMPLING_RATIO, ALISIO_TELEMETRY_CAPTURE_PROMPTS, ALISIO_TELEMETRY_CAPTURE_COMPLETIONS, ALISIO_TELEMETRY_CAPTURE_TOOL_ARGUMENTS, ALISIO_TELEMETRY_CAPTURE_TOOL_RESULTS, ALISIO_TELEMETRY_REDACTION_MODE, ALISIO_TELEMETRY_OTLP_SIGNALS, ALISIO_TELEMETRY_OTLP_GZIP, ALISIO_TELEMETRY_BATCH_SIZE, ALISIO_TELEMETRY_FLUSH_INTERVAL_MS, ALISIO_TELEMETRY_MAX_QUEUE.

The token itself is read only from ALISIO_TELEMETRY_OTLP_TOKEN (or the variable named by otlp.tokenEnv).

Tools

All tools are read-only (read), closed-schema, and return a bounds envelope (window, returned, total, truncated, hint). They never dump raw events and never expose secrets or absolute machine paths.

Tool	Returns
telemetry_summary	Sessions, runs, turns, tokens, tool errors, latency and a time series
telemetry_models	Model mix with token usage, calls and average turn duration
telemetry_tools	Tool call counts, error rate, latency and effects
telemetry_sessions	Recent sessions/runs with bounded metadata
telemetry_search	Bounded content search; only returns content when capture is enabled

Commands

Alisio namespaces external plugin commands as :, so the real invocation form is:

/telemetry:telemetry-setup [options]
/telemetry:telemetry-status
/telemetry:telemetry-flush
/telemetry:telemetry-prune [--days <n>]

telemetry-setup persists configuration non-interactively and reports exactly which fields changed, without ever echoing a credential. Use --json on any of these for machine-readable output.

OpenTelemetry alignment

The plugin emits OTLP/HTTP JSON to /v1/traces, /v1/logs and /v1/metrics under the configured base endpoint. It uses standard names where they exist, for example gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model, gen_ai.response.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.cached_input_tokens, gen_ai.tool.name, gen_ai.tool.call.id, gen_ai.conversation.id, and the stable core attributes error.type, server.address and server.port. Span names follow {gen_ai.operation.name} {target}, using invoke_agent, chat and execute_tool.

Honesty constraint. Every gen_ai.* semantic convention is currently Development/experimental, not stable, and the GenAI conventions moved out of the main semantic-conventions repository. There is no stable release for metrics. These attribute names may change and this plugin claims no stability. Where no standard exists — cost, retry rate, cache-hit ratio, approval outcomes, context growth — the plugin uses clearly namespaced alisio.telemetry.* attributes or metrics instead of inventing gen_ai.* names. Cost and approval outcomes are not captured at all.

Export behavior: HTTP 200 (including a partial-success body) is success and is never retried; only 429, 502, 503 and 504 are retried, with bounded attempts and floor-ed exponential backoff honoring Retry-After. Redirects are refused and response bodies are read through a hard cap. Payloads are persisted as batches keyed by their content hash before any network call, so a failed export stays queued and a retry is idempotent — data is neither lost nor duplicated silently. Non-retryable responses are marked dead and surfaced in telemetry-status rather than discarded.

Deleting telemetry

/telemetry:telemetry-prune [--days ] deletes runs, turns, tool calls and content older than the cutoff, purges the full-text search index, then runs optimize and VACUUM. To remove everything, run it with a cutoff in the future (for example --days 0), or delete the SQLite file directly.

FTS caveat: the full-text search shadow tables (content_fts\*) can retain fragments even after rows are deleted; prune clears the index and vacuums, but a copy of the database made earlier may still contain forensic traces. Treat any captured content as sensitive.

Requirements

Node.js >= 22.16 and an Alisio host with @alisio/sdk>=0.1.0-alpha.10 that provides the SQLite storage port (api.storage.sqlite). Zero runtime dependencies: Node built-ins and native fetch only.

License

MIT.