dsh-observe 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +25 -0
- package/LICENSE +201 -0
- package/README.es.md +198 -0
- package/README.hi.md +198 -0
- package/README.md +198 -0
- package/README.pt.md +198 -0
- package/README.zh.md +198 -0
- package/THIRD_PARTY_NOTICES.md +21 -0
- package/cordis.patch.yml +86 -0
- package/lib/index.js +1947 -0
- package/lib/typert.host.js +109 -0
- package/lib/types/backoff.d.ts +17 -0
- package/lib/types/backoff.d.ts.map +1 -0
- package/lib/types/backoff.js +17 -0
- package/lib/types/backoff.js.map +1 -0
- package/lib/types/collector.d.ts +83 -0
- package/lib/types/collector.d.ts.map +1 -0
- package/lib/types/collector.js +506 -0
- package/lib/types/collector.js.map +1 -0
- package/lib/types/config.d.ts +286 -0
- package/lib/types/config.d.ts.map +1 -0
- package/lib/types/config.js +312 -0
- package/lib/types/config.js.map +1 -0
- package/lib/types/ids.d.ts +43 -0
- package/lib/types/ids.d.ts.map +1 -0
- package/lib/types/ids.js +63 -0
- package/lib/types/ids.js.map +1 -0
- package/lib/types/index.d.ts +35 -0
- package/lib/types/index.d.ts.map +1 -0
- package/lib/types/index.js +162 -0
- package/lib/types/index.js.map +1 -0
- package/lib/types/model.d.ts +89 -0
- package/lib/types/model.d.ts.map +1 -0
- package/lib/types/model.js +25 -0
- package/lib/types/model.js.map +1 -0
- package/lib/types/pipeline.d.ts +71 -0
- package/lib/types/pipeline.d.ts.map +1 -0
- package/lib/types/pipeline.js +193 -0
- package/lib/types/pipeline.js.map +1 -0
- package/lib/types/pricing.d.ts +34 -0
- package/lib/types/pricing.d.ts.map +1 -0
- package/lib/types/pricing.js +45 -0
- package/lib/types/pricing.js.map +1 -0
- package/lib/types/project.d.ts +26 -0
- package/lib/types/project.d.ts.map +1 -0
- package/lib/types/project.js +52 -0
- package/lib/types/project.js.map +1 -0
- package/lib/types/remote.d.ts +28 -0
- package/lib/types/remote.d.ts.map +1 -0
- package/lib/types/remote.js +45 -0
- package/lib/types/remote.js.map +1 -0
- package/lib/types/sanitize.d.ts +78 -0
- package/lib/types/sanitize.d.ts.map +1 -0
- package/lib/types/sanitize.js +132 -0
- package/lib/types/sanitize.js.map +1 -0
- package/lib/types/sinks.d.ts +84 -0
- package/lib/types/sinks.d.ts.map +1 -0
- package/lib/types/sinks.js +434 -0
- package/lib/types/sinks.js.map +1 -0
- package/lib/types/spool.d.ts +113 -0
- package/lib/types/spool.d.ts.map +1 -0
- package/lib/types/spool.js +167 -0
- package/lib/types/spool.js.map +1 -0
- package/lib/types/typert.host.d.ts +93 -0
- package/lib/types/typert.host.d.ts.map +1 -0
- package/lib/types/typert.host.js +23 -0
- package/lib/types/typert.host.js.map +1 -0
- package/lib/types/version.d.ts +10 -0
- package/lib/types/version.d.ts.map +1 -0
- package/lib/types/version.js +10 -0
- package/lib/types/version.js.map +1 -0
- package/lib/types/wire.d.ts +206 -0
- package/lib/types/wire.d.ts.map +1 -0
- package/lib/types/wire.js +71 -0
- package/lib/types/wire.js.map +1 -0
- package/package.json +147 -0
- package/src/backoff.ts +20 -0
- package/src/collector.ts +561 -0
- package/src/config.ts +604 -0
- package/src/ids.ts +68 -0
- package/src/index.ts +186 -0
- package/src/model.ts +100 -0
- package/src/pipeline.ts +205 -0
- package/src/pricing.ts +55 -0
- package/src/project.ts +55 -0
- package/src/remote.ts +56 -0
- package/src/sanitize.ts +132 -0
- package/src/sinks.ts +471 -0
- package/src/spool.ts +196 -0
- package/src/typert.host.ts +24 -0
- package/src/version.ts +10 -0
- package/src/wire.ts +97 -0
package/README.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# 📊 dsh-observe
|
|
4
|
+
|
|
5
|
+
**OpenTelemetry and Langfuse observability exporter for DeepSeek Harness.**
|
|
6
|
+
|
|
7
|
+
*Turn session events into OTLP traces and Langfuse observations — sanitized, buffered, off by default.*
|
|
8
|
+
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](https://github.com/topics/dsh-plugin)
|
|
11
|
+
[](#)
|
|
12
|
+
[](https://github.com/PerryLink/dsh-observe/actions)
|
|
13
|
+
[](https://github.com/PerryLink/dsh-observe/releases)
|
|
14
|
+
[](https://www.npmjs.com/package/dsh-observe)
|
|
15
|
+
[](https://www.npmjs.com/package/dsh-observe)
|
|
16
|
+
|
|
17
|
+
[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Compatibility
|
|
24
|
+
|
|
25
|
+
| Surface | Status |
|
|
26
|
+
|---|---|
|
|
27
|
+
| Harness | DeepSeek Harness `0.1.0-rc.6` |
|
|
28
|
+
| Node | `^22.19.0 \|\| >=24.0.0` |
|
|
29
|
+
| Backends | OpenTelemetry OTLP/HTTP (traces + metrics, JSON encoding) and Langfuse (LLM observability) — either or both |
|
|
30
|
+
| Model | Model-agnostic: it exports the session/event stream; no model calls are made |
|
|
31
|
+
|
|
32
|
+
## What you get
|
|
33
|
+
|
|
34
|
+
`dsh-observe` turns the harness's `session/event` stream into standard observability protocols:
|
|
35
|
+
|
|
36
|
+
- **Spans** — turn, step, tool-call (duration, status, retry derivation), and LLM generation spans, linked into per-turn traces with deterministic ids.
|
|
37
|
+
- **Metrics** — per-provider/model token counters, USD cost counters (configurable pricing table), and the optional context-pressure gauge from `ctx.tokenMeter`.
|
|
38
|
+
- **Sanitized capture** — prompt and completion bodies are redacted (structural key names + built-in secret patterns + your patterns) and truncated before anything is queued or sent.
|
|
39
|
+
- **Reliability** — async batching (size- and timer-triggered), a bounded durable offline buffer (storage-domain) with oldest-first eviction, and deterministic exponential-backoff retries; undeliverable batches survive restarts.
|
|
40
|
+
- **Runtime kill switch** — the optional Typert remote (`observe/status`, `observe/setEnabled`) lets a settings page stop and resume exporting without unmounting.
|
|
41
|
+
- **Off by default** — `enabled: true` plus at least one backend is an explicit opt-in; nothing is captured or exported otherwise.
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
session/event stream
|
|
45
|
+
│ collector (turn/step/tool/llm spans, metrics)
|
|
46
|
+
│ sanitize (keys, secrets, budgets)
|
|
47
|
+
├──▶ pipeline "otlp" ── queue ── flush ──▶ OTLP /v1/traces + /v1/metrics
|
|
48
|
+
│ └─ retry/backoff ─┐
|
|
49
|
+
├──▶ pipeline "langfuse" ── queue ── flush ──▶ Langfuse ingestion
|
|
50
|
+
│ └─ retry/backoff ─┤
|
|
51
|
+
└────────── durable spool (offline buffer, bounded) ◀┘
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
# 1. install the bundle into your profile
|
|
58
|
+
dsh plugin --profile web add "github:PerryLink/dsh-observe#main"
|
|
59
|
+
|
|
60
|
+
# or from npm (published releases)
|
|
61
|
+
dsh plugin --profile web add dsh-observe
|
|
62
|
+
|
|
63
|
+
# 2. configure a backend in your profile patch (cordis.yml) and restart
|
|
64
|
+
dsh --profile web
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Minimal OTLP configuration (the row ships commented out in `cordis.patch.yml`):
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
- insert:
|
|
71
|
+
- id: dsh-observe
|
|
72
|
+
name: dsh-observe
|
|
73
|
+
config:
|
|
74
|
+
enabled: true
|
|
75
|
+
otlp:
|
|
76
|
+
endpoint: http://localhost:4318
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Then verify the row mounts:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
dsh --profile web --dump-config | grep -A2 'id: dsh-observe'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Install & uninstall
|
|
86
|
+
|
|
87
|
+
- **git channel** (latest `main`): `dsh plugin --profile web add "github:PerryLink/dsh-observe#main"` — the `prepare` script builds with production dependencies only.
|
|
88
|
+
- **npm channel** (published releases): `dsh plugin --profile web add dsh-observe`.
|
|
89
|
+
- **tarball channel**: `pnpm pack` in this repo, then `dsh plugin --profile web add ./dsh-observe-<version>.tgz`.
|
|
90
|
+
- **uninstall**: `dsh plugin --profile web remove dsh-observe` (or remove the row from the profile patch).
|
|
91
|
+
|
|
92
|
+
> If pnpm reports `ERR_PNPM_IGNORED_BUILDS` for this package (esbuild's harmless platform-binary validation), add `allowBuilds: { esbuild: true }` to your `pnpm-workspace.yaml` — the `dsh` CLI prints the exact snippet.
|
|
93
|
+
|
|
94
|
+
## Configuration
|
|
95
|
+
|
|
96
|
+
All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need. `cordis.patch.yml` documents each key inline.
|
|
97
|
+
|
|
98
|
+
| Key | Default | Meaning |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| `enabled` | `false` | Master switch; `true` plus at least one backend is the explicit opt-in |
|
|
101
|
+
| `otlp` | `null` | OTLP backend config, or `null` to disable it |
|
|
102
|
+
| `otlp.endpoint` | *(required)* | OTLP base URL; `/v1/traces` and `/v1/metrics` are appended |
|
|
103
|
+
| `otlp.serviceName` | `deepseek-harness` | `service.name` resource attribute |
|
|
104
|
+
| `otlp.serviceVersion` | *(none)* | `service.version` resource attribute |
|
|
105
|
+
| `otlp.headers` | `{}` | Extra headers merged into every export request |
|
|
106
|
+
| `otlp.timeoutMs` | `10000` | Per-request timeout |
|
|
107
|
+
| `langfuse` | `null` | Langfuse backend config, or `null` to disable it |
|
|
108
|
+
| `langfuse.baseUrl` | `https://cloud.langfuse.com` | Langfuse base URL |
|
|
109
|
+
| `langfuse.publicKey` | *(required)* | Project public key |
|
|
110
|
+
| `langfuse.secretKey` | *(required)* | Project secret key |
|
|
111
|
+
| `langfuse.release` | *(none)* | Release tag stamped onto traces |
|
|
112
|
+
| `langfuse.timeoutMs` | `10000` | Per-request timeout |
|
|
113
|
+
| `capture.turns` | `true` | Turn lifecycle spans |
|
|
114
|
+
| `capture.steps` | `true` | Step lifecycle spans |
|
|
115
|
+
| `capture.tools` | `true` | Tool-call spans with sanitized arguments/results |
|
|
116
|
+
| `capture.llm` | `true` | LLM generation spans |
|
|
117
|
+
| `llm.prompt` | `true` | Capture the sanitized request prompt (`false` = sizes only) |
|
|
118
|
+
| `llm.completion` | `true` | Capture the sanitized completion (`false` = sizes only) |
|
|
119
|
+
| `metadata.sessionId` | `true` | Session id attribute |
|
|
120
|
+
| `metadata.cwd` | `false` | Session working directory (a local path — off by default) |
|
|
121
|
+
| `metadata.agentPreset` | `true` | Agent preset id attribute |
|
|
122
|
+
| `metadata.model` | `true` | Provider/model attributes |
|
|
123
|
+
| `metrics.tokens` | `true` | Per-provider/model token counters |
|
|
124
|
+
| `metrics.cost` | `true` | USD cost counters (need `pricing` rules to match) |
|
|
125
|
+
| `metrics.contextTokens` | `true` | Context-pressure gauge (needs `ctx.tokenMeter`) |
|
|
126
|
+
| `pricing` | `[]` | Pricing table, first match wins: `{ provider?, model, inputPerToken, outputPerToken, cacheReadPerToken?, cacheWritePerToken? }` |
|
|
127
|
+
| `sanitize.enabled` | `true` | Redaction master switch (`false` disables redaction, never truncation) |
|
|
128
|
+
| `sanitize.redactKeys` | `[]` | Extra key-name substrings (key/token/secret/password/authorization/credential/apiKey are always included) |
|
|
129
|
+
| `sanitize.redactPatterns` | `[]` | Extra secret regular expressions |
|
|
130
|
+
| `sanitize.truncatePromptChars` | `4000` | Prompt character budget |
|
|
131
|
+
| `sanitize.truncateCompletionChars` | `4000` | Completion character budget |
|
|
132
|
+
| `sanitize.truncateToolInputChars` | `2000` | Tool argument character budget |
|
|
133
|
+
| `sanitize.truncateToolOutputChars` | `2000` | Tool result character budget |
|
|
134
|
+
| `sanitize.truncateAttributeChars` | `512` | Span attribute string budget |
|
|
135
|
+
| `batch.maxRecords` | `256` | Flush once the queue holds this many records |
|
|
136
|
+
| `batch.flushIntervalMs` | `5000` | Timer flush interval |
|
|
137
|
+
| `batch.maxQueueRecords` | `2000` | In-memory queue bound; excess spills to the buffer |
|
|
138
|
+
| `batch.maxBufferRecords` | `10000` | Durable offline buffer bound; oldest records drop first |
|
|
139
|
+
| `batch.bufferRetryIntervalMs` | `30000` | Offline buffer retry interval |
|
|
140
|
+
| `retry.maxAttempts` | `5` | Attempts per batch, including the first try |
|
|
141
|
+
| `retry.baseDelayMs` | `1000` | First backoff delay |
|
|
142
|
+
| `retry.factor` | `2` | Backoff multiplier per consecutive failure |
|
|
143
|
+
| `retry.maxDelayMs` | `60000` | Backoff ceiling |
|
|
144
|
+
| `remote.enabled` | `false` | Mount the `observe` Typert remote (kill switch) |
|
|
145
|
+
|
|
146
|
+
## Tools & surfaces
|
|
147
|
+
|
|
148
|
+
This plugin registers **no model tools** — it is a background exporter. Its surfaces:
|
|
149
|
+
|
|
150
|
+
- **Consumes** `session/event` (span/metric collection), `session/flush` (best-effort export kick — the durability checkpoint never waits on a remote backend), and `session/disposed`.
|
|
151
|
+
- **Optional remote service** `observe` — `observe/status` returns the kill-switch state, configured backends, queue depths, and buffer occupancy; `observe/setEnabled` stops and resumes exporting at runtime.
|
|
152
|
+
|
|
153
|
+
## Permissions & data
|
|
154
|
+
|
|
155
|
+
- **Permissions**: `network:outbound` to the endpoints you configure, `session:read` for the event stream, `storage:write` for the offline buffer; no native code, no filesystem access.
|
|
156
|
+
- **Data**: everything sent is derived from the session log and sanitized (redaction + truncation) before it is queued, buffered, or transmitted. The offline buffer stores only sanitized records, re-validated when read back.
|
|
157
|
+
- **Credentials**: Langfuse public/secret keys travel only to the configured Langfuse endpoint; OTLP headers only to the configured OTLP endpoint. The plugin stores no credentials itself — keep them in credential references or environment-injected values.
|
|
158
|
+
|
|
159
|
+
## Security boundaries
|
|
160
|
+
|
|
161
|
+
- **Off by default** — nothing is captured or exported unless you opt in explicitly.
|
|
162
|
+
- **Sanitize before send** — structural key redaction, built-in secret patterns (API keys, GitHub tokens, AWS keys, bearer credentials, private keys), your patterns, and character budgets all apply before any record leaves memory.
|
|
163
|
+
- **Durable boundary re-validation** — records read back from storage are checked again before a sink can see them.
|
|
164
|
+
- **Failure loud, failure contained** — export failures warn, count, retry, and finally spool; a failing session handler is caught and logged so observability can never break the harness hot path.
|
|
165
|
+
- **Model-visible ⟺ logged** — prompt/completion exports project only the logged header and the session surface; the exporter invents no content.
|
|
166
|
+
|
|
167
|
+
## Known limitations
|
|
168
|
+
|
|
169
|
+
- **rc.6 only** — the plugin is developed and tested against `@deepseek-ai/dsh@0.1.0-rc.6`; newer harness baselines are expected to work but are verified by the monthly compat workflow.
|
|
170
|
+
- **Metrics bypass the retry/spool path** — OTLP metrics are aggregated cumulatively, so a lost flush self-heals on the next one (by design, not a bug).
|
|
171
|
+
- **No sampling** — every enabled span family is exported; set `capture.*` switches and `batch.maxBufferRecords` for high-volume sessions.
|
|
172
|
+
|
|
173
|
+
## Development
|
|
174
|
+
|
|
175
|
+
```sh
|
|
176
|
+
pnpm install # node ^22.19 || >=24
|
|
177
|
+
pnpm run typecheck # tsc: src + tests against the local harness checkout
|
|
178
|
+
pnpm run typecheck:ci # tsc against the published 0.1.0-rc.6 types (no paths)
|
|
179
|
+
pnpm test # vitest: 95 tests, 13 suites (real Context/Session/storage seam)
|
|
180
|
+
pnpm run test:coverage # coverage gate (90/80/90/90)
|
|
181
|
+
pnpm run build # tsdown bundle + tsc declarations (lib/)
|
|
182
|
+
pnpm run verify:self-contained # dependency specs resolve from the registry
|
|
183
|
+
pnpm run verify:artifacts # built ESM face + bundle patch present
|
|
184
|
+
node scripts/check-readme-sync.mjs # five-language README sync gate
|
|
185
|
+
pnpm pack # the published tarball
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Topics
|
|
189
|
+
|
|
190
|
+
`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `observability`, `opentelemetry`, `otlp`, `langfuse`, `tracing`
|
|
191
|
+
|
|
192
|
+
## Contributors
|
|
193
|
+
|
|
194
|
+
- [@PerryLink](https://github.com/PerryLink) — creator and maintainer: collector, pipelines, spool, OTLP/Langfuse sinks, sanitization, and the five-language docs.
|
|
195
|
+
|
|
196
|
+
## License
|
|
197
|
+
|
|
198
|
+
[Apache License 2.0](LICENSE) © 2026 dsh-observe contributors
|
package/README.pt.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# 📊 dsh-observe
|
|
4
|
+
|
|
5
|
+
**Exportador de observabilidade OpenTelemetry e Langfuse para o DeepSeek Harness.**
|
|
6
|
+
|
|
7
|
+
*Transforme eventos de sessão em traces OTLP e observações Langfuse — saneados, com buffer e desligados por padrão.*
|
|
8
|
+
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](https://github.com/topics/dsh-plugin)
|
|
11
|
+
[](#)
|
|
12
|
+
[](https://github.com/PerryLink/dsh-observe/actions)
|
|
13
|
+
[](https://github.com/PerryLink/dsh-observe/releases)
|
|
14
|
+
[](https://www.npmjs.com/package/dsh-observe)
|
|
15
|
+
[](https://www.npmjs.com/package/dsh-observe)
|
|
16
|
+
|
|
17
|
+
[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Compatibility
|
|
24
|
+
|
|
25
|
+
| Superfície | Status |
|
|
26
|
+
|---|---|
|
|
27
|
+
| Harness | DeepSeek Harness `0.1.0-rc.6` |
|
|
28
|
+
| Node | `^22.19.0 \|\| >=24.0.0` |
|
|
29
|
+
| Backends | OpenTelemetry OTLP/HTTP (traces + metrics, codificação JSON) e Langfuse (observabilidade de LLM) — um ou ambos |
|
|
30
|
+
| Modelo | Independente de modelo: exporta o fluxo `session/event`; não faz chamadas a modelos |
|
|
31
|
+
|
|
32
|
+
## What you get
|
|
33
|
+
|
|
34
|
+
O `dsh-observe` transforma o fluxo `session/event` do harness em protocolos padrão de observabilidade:
|
|
35
|
+
|
|
36
|
+
- **Spans** — spans de turno, passo, chamada de ferramenta (duração, status, derivação de tentativas) e geração de LLM, ligados em traces por turno com ids deterministas.
|
|
37
|
+
- **Metrics** — contadores de tokens por provider/modelo, contadores de custo em USD (tabela de preços configurável) e o gauge opcional de pressão de contexto via `ctx.tokenMeter`.
|
|
38
|
+
- **Captura saneada** — corpos de prompt e completion são redigidos (nomes de chave estruturais + padrões de segredos embutidos + seus padrões) e truncados antes de qualquer enfileiramento ou envio.
|
|
39
|
+
- **Confiabilidade** — lotes assíncronos (por tamanho e por temporizador), um buffer offline durável e limitado (storage-domain) com despejo do mais antigo, e tentativas com backoff exponencial determinista; lotes não entregues sobrevivem a reinícios.
|
|
40
|
+
- **Interruptor em tempo de execução** — o Typert remote opcional (`observe/status`, `observe/setEnabled`) permite a uma página de ajustes parar e retomar a exportação sem desmontar.
|
|
41
|
+
- **Desligado por padrão** — `enabled: true` mais ao menos um backend é a adesão explícita; caso contrário, nada é capturado ou exportado.
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
fluxo session/event
|
|
45
|
+
│ collector (spans de turno/passo/ferramenta/LLM, métricas)
|
|
46
|
+
│ sanitize (chaves, segredos, orçamentos)
|
|
47
|
+
├──▶ pipeline "otlp" ── fila ── flush ──▶ OTLP /v1/traces + /v1/metrics
|
|
48
|
+
│ └─ tentativa/backoff ─┐
|
|
49
|
+
├──▶ pipeline "langfuse" ── fila ── flush ──▶ ingestão Langfuse
|
|
50
|
+
│ └─ tentativa/backoff ─┤
|
|
51
|
+
└────────── spool durável (buffer offline, limitado) ◀┘
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
# 1. instale o bundle no seu perfil
|
|
58
|
+
dsh plugin --profile web add "github:PerryLink/dsh-observe#main"
|
|
59
|
+
|
|
60
|
+
# ou pelo npm (versões publicadas)
|
|
61
|
+
dsh plugin --profile web add dsh-observe
|
|
62
|
+
|
|
63
|
+
# 2. configure um backend no patch do seu perfil (cordis.yml) e reinicie
|
|
64
|
+
dsh --profile web
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Configuração OTLP mínima (a linha vem comentada em `cordis.patch.yml`):
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
- insert:
|
|
71
|
+
- id: dsh-observe
|
|
72
|
+
name: dsh-observe
|
|
73
|
+
config:
|
|
74
|
+
enabled: true
|
|
75
|
+
otlp:
|
|
76
|
+
endpoint: http://localhost:4318
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Depois verifique que a linha monta:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
dsh --profile web --dump-config | grep -A2 'id: dsh-observe'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Install & uninstall
|
|
86
|
+
|
|
87
|
+
- **Canal git** (último `main`): `dsh plugin --profile web add "github:PerryLink/dsh-observe#main"` — o script `prepare` compila apenas com dependências de produção.
|
|
88
|
+
- **Canal npm** (versões publicadas): `dsh plugin --profile web add dsh-observe`.
|
|
89
|
+
- **Canal tarball**: `pnpm pack` neste repositório e então `dsh plugin --profile web add ./dsh-observe-<version>.tgz`.
|
|
90
|
+
- **Desinstalar**: `dsh plugin --profile web remove dsh-observe` (ou remova a linha do patch do perfil).
|
|
91
|
+
|
|
92
|
+
> Se o pnpm reportar `ERR_PNPM_IGNORED_BUILDS` para este pacote (a validação inofensiva do binário de plataforma do esbuild), adicione `allowBuilds: { esbuild: true }` ao seu `pnpm-workspace.yaml` — o CLI `dsh` imprime o trecho exato.
|
|
93
|
+
|
|
94
|
+
## Configuration
|
|
95
|
+
|
|
96
|
+
Todos os ajustes são campos `Config` do Schemastery (alteráveis pelo cordis.yml). Uma sobrescrita direcionada por id substitui a linha inteira — redeclare cada chave que precisar. O `cordis.patch.yml` documenta cada chave em linha.
|
|
97
|
+
|
|
98
|
+
| Key | Default | Meaning |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| `enabled` | `false` | Interruptor mestre; `true` mais ao menos um backend é a adesão explícita |
|
|
101
|
+
| `otlp` | `null` | Configuração do backend OTLP, ou `null` para desativá-lo |
|
|
102
|
+
| `otlp.endpoint` | *(obrigatório)* | URL base do OTLP; `/v1/traces` e `/v1/metrics` são acrescentados |
|
|
103
|
+
| `otlp.serviceName` | `deepseek-harness` | Atributo de recurso `service.name` |
|
|
104
|
+
| `otlp.serviceVersion` | *(nenhum)* | Atributo de recurso `service.version` |
|
|
105
|
+
| `otlp.headers` | `{}` | Cabeçalhos extras mesclados em cada requisição de exportação |
|
|
106
|
+
| `otlp.timeoutMs` | `10000` | Tempo limite por requisição |
|
|
107
|
+
| `langfuse` | `null` | Configuração do backend Langfuse, ou `null` para desativá-lo |
|
|
108
|
+
| `langfuse.baseUrl` | `https://cloud.langfuse.com` | URL base do Langfuse |
|
|
109
|
+
| `langfuse.publicKey` | *(obrigatório)* | Chave pública do projeto |
|
|
110
|
+
| `langfuse.secretKey` | *(obrigatório)* | Chave secreta do projeto |
|
|
111
|
+
| `langfuse.release` | *(nenhum)* | Tag de release carimbada nos traces |
|
|
112
|
+
| `langfuse.timeoutMs` | `10000` | Tempo limite por requisição |
|
|
113
|
+
| `capture.turns` | `true` | Spans de ciclo de vida do turno |
|
|
114
|
+
| `capture.steps` | `true` | Spans de ciclo de vida do passo |
|
|
115
|
+
| `capture.tools` | `true` | Spans de chamada de ferramenta com argumentos/resultados saneados |
|
|
116
|
+
| `capture.llm` | `true` | Spans de geração de LLM |
|
|
117
|
+
| `llm.prompt` | `true` | Captura o prompt de requisição saneado (`false` = apenas tamanhos) |
|
|
118
|
+
| `llm.completion` | `true` | Captura a completion saneada (`false` = apenas tamanhos) |
|
|
119
|
+
| `metadata.sessionId` | `true` | Atributo de id de sessão |
|
|
120
|
+
| `metadata.cwd` | `false` | Diretório de trabalho da sessão (um caminho local — desligado por padrão) |
|
|
121
|
+
| `metadata.agentPreset` | `true` | Atributo de id do agent preset |
|
|
122
|
+
| `metadata.model` | `true` | Atributos de provider/modelo |
|
|
123
|
+
| `metrics.tokens` | `true` | Contadores de tokens por provider/modelo |
|
|
124
|
+
| `metrics.cost` | `true` | Contadores de custo em USD (precisam de regras `pricing` que coincidam) |
|
|
125
|
+
| `metrics.contextTokens` | `true` | Gauge de pressão de contexto (precisa de `ctx.tokenMeter`) |
|
|
126
|
+
| `pricing` | `[]` | Tabela de preços, primeira coincidência vence: `{ provider?, model, inputPerToken, outputPerToken, cacheReadPerToken?, cacheWritePerToken? }` |
|
|
127
|
+
| `sanitize.enabled` | `true` | Interruptor mestre de redação (`false` desativa a redação, nunca o truncamento) |
|
|
128
|
+
| `sanitize.redactKeys` | `[]` | Substrings de nome de chave extras (key/token/secret/password/authorization/credential/apiKey sempre incluídas) |
|
|
129
|
+
| `sanitize.redactPatterns` | `[]` | Expressões regulares de segredos extras |
|
|
130
|
+
| `sanitize.truncatePromptChars` | `4000` | Orçamento de caracteres do prompt |
|
|
131
|
+
| `sanitize.truncateCompletionChars` | `4000` | Orçamento de caracteres da completion |
|
|
132
|
+
| `sanitize.truncateToolInputChars` | `2000` | Orçamento de caracteres dos argumentos de ferramenta |
|
|
133
|
+
| `sanitize.truncateToolOutputChars` | `2000` | Orçamento de caracteres do resultado de ferramenta |
|
|
134
|
+
| `sanitize.truncateAttributeChars` | `512` | Orçamento de strings de atributos de span |
|
|
135
|
+
| `batch.maxRecords` | `256` | Flush quando a fila atinge este número de registros |
|
|
136
|
+
| `batch.flushIntervalMs` | `5000` | Intervalo de flush por temporizador |
|
|
137
|
+
| `batch.maxQueueRecords` | `2000` | Limite da fila em memória; o excesso derrama para o buffer |
|
|
138
|
+
| `batch.maxBufferRecords` | `10000` | Limite do buffer offline durável; os registros mais antigos caem primeiro |
|
|
139
|
+
| `batch.bufferRetryIntervalMs` | `30000` | Intervalo de tentativa do buffer offline |
|
|
140
|
+
| `retry.maxAttempts` | `5` | Tentativas por lote, incluindo a primeira |
|
|
141
|
+
| `retry.baseDelayMs` | `1000` | Primeiro atraso de backoff |
|
|
142
|
+
| `retry.factor` | `2` | Multiplicador de backoff por falha consecutiva |
|
|
143
|
+
| `retry.maxDelayMs` | `60000` | Teto do backoff |
|
|
144
|
+
| `remote.enabled` | `false` | Monta o Typert remote `observe` (interruptor) |
|
|
145
|
+
|
|
146
|
+
## Tools & surfaces
|
|
147
|
+
|
|
148
|
+
Este plugin **não registra ferramentas de modelo** — é um exportador em segundo plano. Suas superfícies:
|
|
149
|
+
|
|
150
|
+
- **Consome** `session/event` (coleta de spans/métricas), `session/flush` (impulso de exportação best-effort — o checkpoint de durabilidade nunca espera um backend remoto) e `session/disposed`.
|
|
151
|
+
- **Serviço remote opcional** `observe` — `observe/status` devolve o estado do interruptor, os backends configurados, a profundidade da fila e a ocupação do buffer; `observe/setEnabled` para e retoma a exportação em tempo de execução.
|
|
152
|
+
|
|
153
|
+
## Permissions & data
|
|
154
|
+
|
|
155
|
+
- **Permissões**: `network:outbound` para os endpoints que você configurar, `session:read` para o fluxo de eventos, `storage:write` para o buffer offline; sem código nativo, sem acesso ao sistema de arquivos.
|
|
156
|
+
- **Dados**: tudo o que é enviado deriva do registro de sessão e é saneado (redação + truncamento) antes de enfileirar, armazenar ou transmitir. O buffer offline guarda apenas registros saneados, re-validados ao serem lidos.
|
|
157
|
+
- **Credenciais**: as chaves pública/secreta do Langfuse viajam apenas para o endpoint Langfuse configurado; os cabeçalhos OTLP apenas para o endpoint OTLP configurado. O plugin não armazena credenciais — guarde-as em referências de credenciais ou valores injetados pelo ambiente.
|
|
158
|
+
|
|
159
|
+
## Security boundaries
|
|
160
|
+
|
|
161
|
+
- **Desligado por padrão** — nada é capturado ou exportado sem adesão explícita.
|
|
162
|
+
- **Sanear antes de enviar** — redação estrutural de chaves, padrões de segredos embutidos (chaves de API, tokens do GitHub, chaves da AWS, credenciais bearer, chaves privadas), seus padrões e orçamentos de caracteres aplicam-se antes de qualquer registro sair da memória.
|
|
163
|
+
- **Re-validação no limite durável** — registros lidos do armazenamento são checados novamente antes que um sink possa vê-los.
|
|
164
|
+
- **Falha ruidosa, falha contida** — falhas de exportação avisam, contam, tentam de novo e por fim vão para o spool; um manipulador de sessão que falha é capturado e registrado, de modo que a observabilidade nunca pode quebrar o caminho quente do harness.
|
|
165
|
+
- **Model-visible ⟺ logged** — as exportações de prompt/completion projetam apenas o cabeçalho registrado e a superfície da sessão; o exportador não inventa conteúdo.
|
|
166
|
+
|
|
167
|
+
## Known limitations
|
|
168
|
+
|
|
169
|
+
- **Somente rc.6** — o plugin é desenvolvido e testado contra `@deepseek-ai/dsh@0.1.0-rc.6`; baselines mais novos devem funcionar e são verificados pelo workflow compat mensal.
|
|
170
|
+
- **Métricas evitam o caminho de tentativa/spool** — as métricas OTLP são agregadas cumulativamente, então um flush perdido se autocura no seguinte (por design, não é um bug).
|
|
171
|
+
- **Sem amostragem** — toda família de spans habilitada é exportada; ajuste os interruptores `capture.*` e `batch.maxBufferRecords` para sessões de alto volume.
|
|
172
|
+
|
|
173
|
+
## Development
|
|
174
|
+
|
|
175
|
+
```sh
|
|
176
|
+
pnpm install # node ^22.19 || >=24
|
|
177
|
+
pnpm run typecheck # tsc: src + tests contra o checkout local do harness
|
|
178
|
+
pnpm run typecheck:ci # tsc contra os tipos publicados 0.1.0-rc.6 (sem paths)
|
|
179
|
+
pnpm test # vitest: 95 testes, 13 suítes (Context/Session/storage seam reais)
|
|
180
|
+
pnpm run test:coverage # porta de cobertura (90/80/90/90)
|
|
181
|
+
pnpm run build # bundle tsdown + declarações tsc (lib/)
|
|
182
|
+
pnpm run verify:self-contained # as especificações de dependências resolvem pelo registry
|
|
183
|
+
pnpm run verify:artifacts # face ESM construída + bundle patch presentes
|
|
184
|
+
node scripts/check-readme-sync.mjs # porta de sincronia dos cinco READMEs
|
|
185
|
+
pnpm pack # o tarball publicado
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Topics
|
|
189
|
+
|
|
190
|
+
`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `observability`, `opentelemetry`, `otlp`, `langfuse`, `tracing`
|
|
191
|
+
|
|
192
|
+
## Contributors
|
|
193
|
+
|
|
194
|
+
- [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: collector, pipelines, spool, sinks OTLP/Langfuse, saneamento e a documentação em cinco idiomas.
|
|
195
|
+
|
|
196
|
+
## License
|
|
197
|
+
|
|
198
|
+
[Apache License 2.0](LICENSE) © 2026 dsh-observe contributors
|
package/README.zh.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# 📊 dsh-observe
|
|
4
|
+
|
|
5
|
+
**DeepSeek Harness 的 OpenTelemetry 与 Langfuse 可观测性导出器。**
|
|
6
|
+
|
|
7
|
+
*把会话事件变成 OTLP 追踪与 Langfuse 观测 —— 脱敏、缓冲、默认关闭。*
|
|
8
|
+
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](https://github.com/topics/dsh-plugin)
|
|
11
|
+
[](#)
|
|
12
|
+
[](https://github.com/PerryLink/dsh-observe/actions)
|
|
13
|
+
[](https://github.com/PerryLink/dsh-observe/releases)
|
|
14
|
+
[](https://www.npmjs.com/package/dsh-observe)
|
|
15
|
+
[](https://www.npmjs.com/package/dsh-observe)
|
|
16
|
+
|
|
17
|
+
[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Compatibility
|
|
24
|
+
|
|
25
|
+
| 方面 | 状态 |
|
|
26
|
+
|---|---|
|
|
27
|
+
| Harness | DeepSeek Harness `0.1.0-rc.6` |
|
|
28
|
+
| Node | `^22.19.0 \|\| >=24.0.0` |
|
|
29
|
+
| 后端 | OpenTelemetry OTLP/HTTP(traces + metrics,JSON 编码)与 Langfuse(LLM 可观测)——二选一或同时 |
|
|
30
|
+
| 模型 | 与模型无关:它导出 session/event 流,自身不调用任何模型 |
|
|
31
|
+
|
|
32
|
+
## What you get
|
|
33
|
+
|
|
34
|
+
`dsh-observe` 把 harness 的 `session/event` 流变成标准可观测协议:
|
|
35
|
+
|
|
36
|
+
- **Spans** —— turn、step、工具调用(耗时/状态/重试推导)与 LLM 生成 span,按 turn 连成 trace,id 确定性可重放。
|
|
37
|
+
- **Metrics** —— 按 provider/model 的 token 计数、USD 成本计数(可配价格表)、以及可选的 `ctx.tokenMeter` 上下文压力 gauge。
|
|
38
|
+
- **脱敏采集** —— prompt 与 completion 正文先经结构性键名脱敏 + 内置密钥模式 + 自定义模式 + 字符预算截断,之后才进入队列或发送。
|
|
39
|
+
- **可靠性** —— 异步批量(数量/定时触发)、有界持久离线缓冲(storage-domain,最旧优先淘汰)、确定性指数退避重试;未送达批次重启后仍在。
|
|
40
|
+
- **运行时总开关** —— 可选 Typert remote(`observe/status`、`observe/setEnabled`)让设置页在不卸载的情况下停止/恢复导出。
|
|
41
|
+
- **默认关闭** —— `enabled: true` 且至少配置一个后端才是显式开启;否则不采集、不导出。
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
session/event 流
|
|
45
|
+
│ collector(turn/step/tool/llm span、metrics)
|
|
46
|
+
│ sanitize(键名、密钥、预算)
|
|
47
|
+
├──▶ pipeline "otlp" ── 队列 ── flush ──▶ OTLP /v1/traces + /v1/metrics
|
|
48
|
+
│ └─ 重试/退避 ──┐
|
|
49
|
+
├──▶ pipeline "langfuse" ── 队列 ── flush ──▶ Langfuse ingestion
|
|
50
|
+
│ └─ 重试/退避 ──┤
|
|
51
|
+
└────────── 持久 spool(离线缓冲,有界)◀┘
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
# 1. 把 bundle 装进你的 profile
|
|
58
|
+
dsh plugin --profile web add "github:PerryLink/dsh-observe#main"
|
|
59
|
+
|
|
60
|
+
# 或从 npm 安装(正式发布版)
|
|
61
|
+
dsh plugin --profile web add dsh-observe
|
|
62
|
+
|
|
63
|
+
# 2. 在 profile patch(cordis.yml)里配置后端并重启
|
|
64
|
+
dsh --profile web
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
最小 OTLP 配置(`cordis.patch.yml` 里该行默认注释掉):
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
- insert:
|
|
71
|
+
- id: dsh-observe
|
|
72
|
+
name: dsh-observe
|
|
73
|
+
config:
|
|
74
|
+
enabled: true
|
|
75
|
+
otlp:
|
|
76
|
+
endpoint: http://localhost:4318
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
然后核实行挂载:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
dsh --profile web --dump-config | grep -A2 'id: dsh-observe'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Install & uninstall
|
|
86
|
+
|
|
87
|
+
- **git 通道**(最新 `main`):`dsh plugin --profile web add "github:PerryLink/dsh-observe#main"` —— `prepare` 脚本仅用生产依赖构建。
|
|
88
|
+
- **npm 通道**(正式发布版):`dsh plugin --profile web add dsh-observe`。
|
|
89
|
+
- **tarball 通道**:在本仓库执行 `pnpm pack`,然后 `dsh plugin --profile web add ./dsh-observe-<version>.tgz`。
|
|
90
|
+
- **卸载**:`dsh plugin --profile web remove dsh-observe`(或从 profile patch 中删除该行)。
|
|
91
|
+
|
|
92
|
+
> 如果 pnpm 对本包报 `ERR_PNPM_IGNORED_BUILDS`(esbuild 的平台二进制无害校验),在你的 `pnpm-workspace.yaml` 中加入 `allowBuilds: { esbuild: true }` —— `dsh` CLI 会打印确切片段。
|
|
93
|
+
|
|
94
|
+
## Configuration
|
|
95
|
+
|
|
96
|
+
所有可调项都是 Schemastery `Config` 字段(可在 cordis.yml 中修改)。按 id 定向覆盖会替换整行 —— 需要重新声明每个键。`cordis.patch.yml` 内联说明了每个键。
|
|
97
|
+
|
|
98
|
+
| Key | Default | Meaning |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| `enabled` | `false` | 总开关;`true` 且至少一个后端才是显式开启 |
|
|
101
|
+
| `otlp` | `null` | OTLP 后端配置,`null` 表示禁用 |
|
|
102
|
+
| `otlp.endpoint` | *(必填)* | OTLP 基础 URL;`/v1/traces` 与 `/v1/metrics` 由插件追加 |
|
|
103
|
+
| `otlp.serviceName` | `deepseek-harness` | `service.name` 资源属性 |
|
|
104
|
+
| `otlp.serviceVersion` | *(无)* | `service.version` 资源属性 |
|
|
105
|
+
| `otlp.headers` | `{}` | 合并进每个导出请求的额外请求头 |
|
|
106
|
+
| `otlp.timeoutMs` | `10000` | 单请求超时 |
|
|
107
|
+
| `langfuse` | `null` | Langfuse 后端配置,`null` 表示禁用 |
|
|
108
|
+
| `langfuse.baseUrl` | `https://cloud.langfuse.com` | Langfuse 基础 URL |
|
|
109
|
+
| `langfuse.publicKey` | *(必填)* | 项目公钥 |
|
|
110
|
+
| `langfuse.secretKey` | *(必填)* | 项目密钥 |
|
|
111
|
+
| `langfuse.release` | *(无)* | 打在各 trace 上的 release 标签 |
|
|
112
|
+
| `langfuse.timeoutMs` | `10000` | 单请求超时 |
|
|
113
|
+
| `capture.turns` | `true` | turn 生命周期 span |
|
|
114
|
+
| `capture.steps` | `true` | step 生命周期 span |
|
|
115
|
+
| `capture.tools` | `true` | 工具调用 span(参数/结果脱敏) |
|
|
116
|
+
| `capture.llm` | `true` | LLM 生成 span |
|
|
117
|
+
| `llm.prompt` | `true` | 采集脱敏后的请求 prompt(`false` 只记大小) |
|
|
118
|
+
| `llm.completion` | `true` | 采集脱敏后的 completion(`false` 只记大小) |
|
|
119
|
+
| `metadata.sessionId` | `true` | 会话 id 属性 |
|
|
120
|
+
| `metadata.cwd` | `false` | 会话工作目录(本地路径——默认关闭) |
|
|
121
|
+
| `metadata.agentPreset` | `true` | agent preset id 属性 |
|
|
122
|
+
| `metadata.model` | `true` | provider/model 属性 |
|
|
123
|
+
| `metrics.tokens` | `true` | 按 provider/model 的 token 计数 |
|
|
124
|
+
| `metrics.cost` | `true` | USD 成本计数(需 `pricing` 规则匹配) |
|
|
125
|
+
| `metrics.contextTokens` | `true` | 上下文压力 gauge(需 `ctx.tokenMeter`) |
|
|
126
|
+
| `pricing` | `[]` | 价格表,首个匹配生效:`{ provider?, model, inputPerToken, outputPerToken, cacheReadPerToken?, cacheWritePerToken? }` |
|
|
127
|
+
| `sanitize.enabled` | `true` | 脱敏总开关(`false` 只关脱敏,不关截断) |
|
|
128
|
+
| `sanitize.redactKeys` | `[]` | 额外键名子串(key/token/secret/password/authorization/credential/apiKey 恒生效) |
|
|
129
|
+
| `sanitize.redactPatterns` | `[]` | 额外密钥正则 |
|
|
130
|
+
| `sanitize.truncatePromptChars` | `4000` | prompt 字符预算 |
|
|
131
|
+
| `sanitize.truncateCompletionChars` | `4000` | completion 字符预算 |
|
|
132
|
+
| `sanitize.truncateToolInputChars` | `2000` | 工具参数字符预算 |
|
|
133
|
+
| `sanitize.truncateToolOutputChars` | `2000` | 工具结果字符预算 |
|
|
134
|
+
| `sanitize.truncateAttributeChars` | `512` | span 属性字符串预算 |
|
|
135
|
+
| `batch.maxRecords` | `256` | 队列达到该数量即 flush |
|
|
136
|
+
| `batch.flushIntervalMs` | `5000` | 定时 flush 间隔 |
|
|
137
|
+
| `batch.maxQueueRecords` | `2000` | 内存队列上限;超出溢入缓冲 |
|
|
138
|
+
| `batch.maxBufferRecords` | `10000` | 持久离线缓冲上限;最旧记录先丢 |
|
|
139
|
+
| `batch.bufferRetryIntervalMs` | `30000` | 离线缓冲重试间隔 |
|
|
140
|
+
| `retry.maxAttempts` | `5` | 每批尝试次数(含首次) |
|
|
141
|
+
| `retry.baseDelayMs` | `1000` | 首次退避延迟 |
|
|
142
|
+
| `retry.factor` | `2` | 每连续失败一次的退避倍数 |
|
|
143
|
+
| `retry.maxDelayMs` | `60000` | 退避上限 |
|
|
144
|
+
| `remote.enabled` | `false` | 挂载 `observe` Typert remote(总开关) |
|
|
145
|
+
|
|
146
|
+
## Tools & surfaces
|
|
147
|
+
|
|
148
|
+
本插件**不注册任何模型工具** —— 它是后台导出器。其界面:
|
|
149
|
+
|
|
150
|
+
- **消费** `session/event`(span/metric 采集)、`session/flush`(尽力导出 kick —— 持久化检查点绝不等待远端后端)、`session/disposed`。
|
|
151
|
+
- **可选 remote 服务** `observe` —— `observe/status` 返回总开关状态、已配置后端、队列深度与缓冲占用;`observe/setEnabled` 在运行时停止/恢复导出。
|
|
152
|
+
|
|
153
|
+
## Permissions & data
|
|
154
|
+
|
|
155
|
+
- **权限**:对你配置的端点出网(`network:outbound`)、读取事件流(`session:read`)、写离线缓冲(`storage:write`);无原生代码、无文件系统访问。
|
|
156
|
+
- **数据**:所有外发内容都来自会话日志,并在入队、缓冲、发送前完成脱敏(脱敏 + 截断)。离线缓冲只存脱敏记录,读回时再次校验。
|
|
157
|
+
- **凭据**:Langfuse 公钥/密钥只发往你配置的 Langfuse 端点;OTLP 请求头只发往你配置的 OTLP 端点。插件自身不存任何凭据 —— 请使用凭据引用或环境注入。
|
|
158
|
+
|
|
159
|
+
## Security boundaries
|
|
160
|
+
|
|
161
|
+
- **默认关闭** —— 不显式开启则不采集、不导出。
|
|
162
|
+
- **发送前脱敏** —— 结构性键名脱敏、内置密钥模式(API key、GitHub token、AWS key、bearer 凭据、私钥)、自定义模式与字符预算,全部在任何记录离开内存前生效。
|
|
163
|
+
- **持久边界再校验** —— 从存储读回的记录在到达 sink 前再次检查。
|
|
164
|
+
- **失败大声、失败隔离** —— 导出失败会告警、计数、重试并最终入缓冲;会话事件处理失败被捕获并记录,可观测性永远不会拖垮 harness 热路径。
|
|
165
|
+
- **模型可见 ⟺ 已记录** —— prompt/completion 导出只投影已记录的 header 与会话 surface;导出器不发明任何内容。
|
|
166
|
+
|
|
167
|
+
## Known limitations
|
|
168
|
+
|
|
169
|
+
- **仅 rc.6** —— 插件针对 `@deepseek-ai/dsh@0.1.0-rc.6` 开发与测试;更新的 harness 基线预期可用,由月度 compat 工作流验证。
|
|
170
|
+
- **Metrics 不走重试/缓冲路径** —— OTLP metrics 按累计聚合,丢失一次 flush 会在下一次自愈(设计如此,非缺陷)。
|
|
171
|
+
- **无采样** —— 每个启用的 span 族都会导出;大流量会话请调整 `capture.*` 开关与 `batch.maxBufferRecords`。
|
|
172
|
+
|
|
173
|
+
## Development
|
|
174
|
+
|
|
175
|
+
```sh
|
|
176
|
+
pnpm install # node ^22.19 || >=24
|
|
177
|
+
pnpm run typecheck # tsc:src + tests,对照本地 harness checkout
|
|
178
|
+
pnpm run typecheck:ci # tsc:对照已发布的 0.1.0-rc.6 类型(无 paths)
|
|
179
|
+
pnpm test # vitest:95 个测试、13 个套件(真实 Context/Session/storage 接缝)
|
|
180
|
+
pnpm run test:coverage # 覆盖率门禁(90/80/90/90)
|
|
181
|
+
pnpm run build # tsdown bundle + tsc 声明(lib/)
|
|
182
|
+
pnpm run verify:self-contained # 依赖声明全部来自 registry
|
|
183
|
+
pnpm run verify:artifacts # 构建产物 ESM 面 + bundle patch 齐全
|
|
184
|
+
node scripts/check-readme-sync.mjs # 五语 README 同步门
|
|
185
|
+
pnpm pack # 发布用 tarball
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Topics
|
|
189
|
+
|
|
190
|
+
`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `observability`, `opentelemetry`, `otlp`, `langfuse`, `tracing`
|
|
191
|
+
|
|
192
|
+
## Contributors
|
|
193
|
+
|
|
194
|
+
- [@PerryLink](https://github.com/PerryLink) —— 创建者与维护者:collector、pipeline、spool、OTLP/Langfuse sink、脱敏层与五语文档。
|
|
195
|
+
|
|
196
|
+
## License
|
|
197
|
+
|
|
198
|
+
[Apache License 2.0](LICENSE) © 2026 dsh-observe contributors
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
`dsh-observe` bundles no third-party source code. All TypeScript/JavaScript
|
|
4
|
+
sources in this repository are original works by the dsh-observe
|
|
5
|
+
contributors, licensed under Apache-2.0 (see `LICENSE`).
|
|
6
|
+
|
|
7
|
+
The package depends on the following software. None of it is bundled into the
|
|
8
|
+
published tarball; these are install-time dependencies:
|
|
9
|
+
|
|
10
|
+
| Package | Version range | License | Purpose |
|
|
11
|
+
|---|---|---|---|
|
|
12
|
+
| [tsdown](https://github.com/rolldown/tsdown) | `^0.22.14` | MIT | Build-time bundling of `lib/` (a regular dependency so the git-install channel's `prepare` script can build) |
|
|
13
|
+
| [typescript](https://github.com/microsoft/TypeScript) | `^5.9.0` | Apache-2.0 | Build-time declaration emission (`lib/types/`) |
|
|
14
|
+
| [zod](https://github.com/colinhacks/zod) | `^4.4.3` | MIT | Runtime value schema for the durable offline-buffer domain table |
|
|
15
|
+
| [@deepseek-ai/cordis](https://www.npmjs.com/package/@deepseek-ai/cordis) | `^4.0.1` (peer) | See package | The plugin runtime |
|
|
16
|
+
| [@deepseek-ai/schemastery](https://www.npmjs.com/package/@deepseek-ai/schemastery) | `^3.18.0` (peer) | See package | Configuration schema |
|
|
17
|
+
| `@deepseek-ai/dsh-*` peers | `0.1.0-rc.6` (peer) | See packages | Official harness seams (`dsh-session`, `dsh-llm`, `dsh-storage-domain`, `dsh-typert-protocol`) |
|
|
18
|
+
|
|
19
|
+
At runtime the plugin only talks to the harness services listed as
|
|
20
|
+
peerDependencies and to the observability endpoints **you** configure; it
|
|
21
|
+
performs no other network requests.
|