create-evlog-adapter
/create-evlog-adapter
Tworzy nowy wbudowany adapter evlog, który wysyła szerokie zdarzenia do zewnętrznej platformy obserwacyjnej, z testami i dokumentacją.
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Tworzy nowy wbudowany adapter evlog, który wysyła szerokie zdarzenia do zewnętrznej platformy obserwacyjnej, z testami i dokumentacją.
Oryginalny opis (EN)
Create a new built-in evlog adapter to send wide events to an external observability platform. Use when adding a new drain adapter (e.g., for Elasticsearch, Honeycomb, SigNoz, etc.) to the evlog package. Covers source code, build config, package exports, tests, e2e, and all documentation.
Jak działa
- PR Title
- Touchpoints Checklist
- Naming Conventions
- Step 1: Adapter Source: built on defineHttpDrain
- Step 2: Build Config
- Step 3: Package Exports
- Step 4: Unit Tests
- Step 5: E2E Test + Sandbox
- Step 6: Adapter Documentation Page
- Step 7: Update Adapters Overview Page
Podgląd SKILL.md
---
name: create-evlog-adapter
description: Create a new built-in evlog adapter to send wide events to an external observability platform. Use when adding a new drain adapter (e.g., for Elasticsearch, Honeycomb, SigNoz, etc.) to the evlog package. Covers source code, build config, package exports, tests, e2e, and all documentation.
metadata:
internal: true
---
# Create evlog Adapter
Add a new built-in adapter to evlog. Every adapter follows the same architecture and is built on the public toolkit primitives in `evlog/toolkit`, so a community adapter has the same shape as a built-in one.
## PR Title
```
feat({name}): add the {Name} drain adapter
```
Recent examples: `feat(loki): add the Grafana Loki drain adapter`, `feat(clickhouse): add the ClickHouse drain adapter`. Use the adapter name as the conventional-commit scope, and register that scope (see touchpoint 11).
**Scope timing caveat**: the semantic PR check reads its scope list from the **base branch**, so a brand-new scope can't validate the very PR that introduces it. Either register the scope in a small preceding PR (the Loki/ClickHouse pattern), or use an unscoped title (`feat: add the {Name} drain adapter`) on the introducing PR.
## Touchpoints Checklist
| # | File | Action |
|---|------|--------|
| 1 | `packages/evlog/src/adapters/{name}.ts` | Create adapter source (built on `defineHttpDrain` from `../shared/drain`) |
| 2 | `packages/evlog/tsdown.config.ts` | Add build entry |
| 3 | `packages/evlog/package.json` | Add `exports` + `typesVersions` entries |
| 4 | `packages/evlog/test/adapters/{name}.test.ts` | Create unit tests (use `test/helpers/fetch.ts`) |
| 5 | `packages/evlog/test/e2e/{name}.e2e.ts` | Create e2e test gated on env vars; extend the docker sandbox if self-hostable |
| 6 | `packages/evlog/test/toolkit/__snapshots__/api-surface.test.ts.snap` | Regenerated by running the tests after a build (`pnpm run build` then `pnpm test`) |
| 7 | `apps/docs/content/4.integrate/adapters/{category}/{NN}.{name}.md` | Create adapter doc page in the right category |
| 8 | `apps/docs/content/4.integrate/adapters/01.overview.md` | Add adapter to overview (frontmatter link + card) |
| 9 | `skills/review-logging-patterns/SKILL.md` | Add adapter row in the Drain Adapters table + frontmatter description |
| 10 | `.changeset/{name}-adapter.md` | Create changeset (`minor`) describing the adapter |
| 11 | `.github/workflows/semantic-pull-request.yml` + `.github/pull_request_template.md` | Register `{name}` as a PR scope in both files |
| 12 | `.agents/skills/create-adapter/references/upstream-alignment.md` | Add the adapter's row: ingest docs URL, official client repo and package, the file that builds the request, the files where the client feeds the provider's other features such as issues, metrics or user profiles (`none` when the provider only stores what we send), `Aligned to` set to the client version you read while writing the adapter |
**Important**: Do NOT consider the task complete until all 12 touchpoints have been addressed.
## Naming Conventions
Use these placeholders consistently:
| Placeholder | Example (Loki) | Usage |
|-------------|----------------|-------|
| `{name}` | `loki` | File names, import paths, env var suffix, PR scope |
| `{Name}` | `Loki` | PascalCase in function/interface names |
| `{NAME}` | `LOKI` | SCREAMING_CASE in env var prefixes |
Standard option naming (use these exact names):
| Concept | Standard option name |
|---------|---------------------|
| Bearer-style API secret | `apiKey` |
| Base URL of the ingest API | `endpoint` |
| Service identifier | `serviceName` |
| Request timeout (ms) | `timeout` |
| Retry attempts on transient failures | `retries` |
If a service historically used a different name (`token`, `sourceToken`, …) keep it as a deprecated alias via `applyDeprecatedAlias`. See Axiom and Better Stack for the pattern.
## Step 1: Adapter Source: built on `defineHttpDrain`
Create `packages/evlog/src/adapters/{name}.ts`. Read [references/adapter-template.md](references/adapter-template.md) for the full annotated template. `loki.ts` and `clickhouse.ts` are the most recent reference implementations.
The contract is `defineHttpDrain<TConfig>({ name, label, resolve, encode })`. You only ship two pieces of logic:
1. **`resolve()`**: produce a fully-resolved config or `null` to skip. Use `resolveAdapterConfig` for the standard precedence (overrides → `runtimeConfig.evlog.{name}` → `runtimeConfig.{name}` → env vars). List `NUXT_{NAME}_*` before `{NAME}_*` in `ConfigField.env` for silent Nuxt compat; show only `{NAME}_*` in user-facing messages via `formatPublicEnvKeys`.
2. **`encode(events, config)`**: a private `encode{Name}Request(events, config): HttpDrainRequest` returning `{ url, headers, body }` for a batch. HTTP transport, identity headers, retries, timeout, and error logging are handled by `defineHttpDrain` (via `httpPost`).
Key rules:
- **Single factory.** Export one `create{Name}Drain(overrides?: Partial<{Name}Config>)`. No dual-API factories: if a service has multiple ingest modes (logs vs events), expose them via a `mode` option (see PostHog).
- **No HTTP code in the adapter.** Never call `fetch` directly. If the service truly needs custom transport (binary envelopes, non-HTTP), use `defineDrain` from `../shared/drain` instead, see `fs.ts` and `memory.ts`.
- **Encode parity.** The standalone `sendTo{Name}` / `sendBatchTo{Name}` helpers must reuse the same private `encode{Name}Request()` and go through `sendEncodedDrainRequest(request, { label, source, timeout, retries })`, never a separate fetch path. `test/adapters/encode-parity.test.ts` pins this for a subset of adapters; add the new one to it (not every existing adapter is registered there yet, and that is a gap, not a license to skip).
- **Per-request limits.** If the provider documents a cap on entries or bytes per request, split in `sendBatchTo{Name}`: serialize each entry once, group with `chunkSerialized(entries, maxEntries, maxBytes)` from `../shared/chunk`, and send one request per chunk. With an entry cap, serialize one window of `maxEntries` at a time, as `datadog.ts` and `sentry.ts` do, so a large batch is never held serialized in full. The factory then uses `defineDrain` with `send: sendBatchTo{Name}` and `rawSend` forcing `retries: config.retries ?? 0`, as `datadog.ts` and `sentry.ts` do. Name each cap in a constant with the provider's documented value, and record it in `references/upstream-alignment.md`.
- **No bespoke config resolution.** Always go through `resolveAdapterConfig`. Deprecated aliases (`token` → `apiKey`) go through `applyDeprecatedAlias`.
- **Exported converters.** If the service needs a specific event shape, export `to{Name}Event()` / `build{Name}Payload()` helpers so they're testable independently.
- **Edge-safe.** Adapters run on Cloudflare Workers: no `Buffer` (use `TextEncoder` + `btoa`, see `loki.ts`), no Node-only APIs. `fs.ts` shows the `isEdgeRuntime()` guard pattern when a runtime genuinely can't be supported.
## Step 2: Build Config
Add a build entry in `packages/evlog/tsdown.config.ts` alongside the existing adapters:
```typescript
'adapters/{name}': 'src/adapters/{name}.ts',
```
Follow the existing ordering in that file.
## Step 3: Package Exports
In `packages/evlog/package.json`, add two entries (after the last adapter, and check the current list rather than assuming):
**In `exports`**:
```json
"./{name}": {
"types": "./dist/adapters/{name}.d.mts",
"import": "./dist/adapters/{name}.mjs",
"default": "./dist/adapters/{name}.mjs"
}
```
**In `typesVersions["*"]`**:
```json
"{name}": [
"./dist/adapters/{name}.d.mts"
]
```
`test/toolkit/entrypoint-registry.test.ts` checks the three registrations against each other and runs without a build. It fails when the subpath is missing from `typesVersions["*"]` or `tsdown.config.ts`, or when `import` and `default` do not point at the `.mjs` next to `types`. A tsdown entry with no export is not reported, because internal chunks are built that way.
## Step 4: Unit Tests
Create `packages/evlog/test/adapters/{name}.test.ts`. Read [references/test-template.md](references/test-template.md) for the full annotated template, and `packages/evlog/test/README.md` for the repo-wide conventions.
Non-negotiables from the test README:
- Use `mockFetch()` / `getFetchCall` / `getFetchJson` / `getFetchHeaders` from `test/helpers/fetch.ts`, never hand-roll `vi.spyOn(globalThis, 'fetch')` boilerplate.
- Clean up any env vars the adapter reads in `afterEach`.
- Test the exported pure helpers (`to{Name}Event`, `build{Name}Payload`, URL resolvers) directly, one `describe` per helper.
Required test categories:
1. URL construction (default + custom endpoint, trailing-slash tolerance)
2. Headers (auth, content-type, service-specific)
3. Request body format (JSON structure matches service API)
4. Skip behavior when `apiKey` (or required field) is missing
5. Batch operations (multiple events in one request, empty batch skips fetch)
6. Deprecated alias still works (when applicable)
7. Add the adapter to `test/adapters/encode-parity.test.ts`
## Step 5: E2E Test + Sandbox
Create `packages/evlog/test/e2e/{name}.e2e.ts`, gated on the adapter's env vars (skipped when absent). Run with `pnpm test:e2e`.
If the service is self-hostable, extend the local sandbox so the adapter can be exercised without cloud credentials:
- `packages/evlog/test/e2e/docker-compose.yml`: add the service
- `packages/evlog/test/e2e/seed.mjs`: fan the seeder out to the new backend
- `packages/evlog/test/e2e/README.md`: document it
- Root `package.json` `sandbox:e2e` script: add the local env var if needed
See the Loki and ClickHouse setups as references.
## Step 6: Adapter Documentation Page
Read `apps/docs/AGENTS.md` before touching anything under `apps/docs/` (steps 6 to 8).
Adapter docs live in three categories under `apps/docs/content/4.integrate/adapters/`:
| Category | Directory | Examples |
|----------|-----------|----------|
| Cloud (SaaS only) | `cloud/` | Axiom, PostHog, Sentry, Better Stack, Datadog |
| Cloud or Self-Hosted | `hybrid/` | Loki, ClickHouse, OTLP, HyperDX |
| Self-Hosted (local only) | `self-hosted/` | FS, NuxtHub, Memory |
Create `{NN}.{name}.md` in the right category with the next available number. Use the Loki page (`hybrid/01.loki.md`) as a reference for frontmatter, tone, and sections. Key sections: intro, quick setup, configuration (env vars table + priority), advanced usage, querying in the target service, troubleshooting, direct API usage, next steps.
**Important: multi-framework examples.** The Quick Start section must include a `::framework-tabs` group with one fence per supported framework (Nuxt, Nitro, Next.js, SvelteKit, TanStack Start, React Router, Hono, Express, Fastify, Elysia, NestJS, oRPC, Cloudflare Workers, Standalone), the framework in the bracket label. Copy the Axiom page's group and swap the drain factory. Do not only show Nitro examples, and put nothing but fences inside the group.
## Step 7: Update Adapters Overview Page
Edit `apps/docs/content/4.integrate/adapters/01.overview.md` in **two** places (follow the pattern of existing adapters):
1. **Frontmatter `links` array**: add a link entry with icon and `/integrate/adapters/{category}/{name}` path, in category order
2. **`::card-group` section**: add a card block in the matching position
## Step 8: Update the Public Skill
In `skills/review-logging-patterns/SKILL.md` (published on evlog.dev via `/.well-known/skills/`):
1. Add a row to the **Drain Adapters** table: `| {Name} | evlog/{name} | {NAME}_API_KEY, ... |`
2. Add the adapter name to the `description:` line in the YAML frontmatter
## Step 9: Changeset
Create `.changeset/{name}-adapter.md` with a `minor` bump. Write it like a release note: what the adapter does, the deployment modes it covers, the key options, the env vars, and the direct-send helpers. See `.changeset` entries from the Loki/ClickHouse PRs for the expected depth.
## Step 10: PR Scopes
Add `{name}` to the `scopes` list in `.github/workflows/semantic-pull-request.yml` **and** to the Scopes section of `.github/pull_request_template.md`, in alphabetical order. Remember the timing caveat from the PR Title section: this registration only takes effect for PRs whose base branch already contains it.
## Verification
After a clean install, prepare generated workspace types from the repo root first, then run the package checks:
```bash
pnpm run dev:prepare
cd packages/evlog
pnpm run lint
pnpm run typecheck
pnpm run build # required before test — api-surface snapshot is gated on dist/
pnpm run test
```
Pliki w paczce (4)
- SKILL.md 12 KB
- references/adapter-template.md 7 KB
- references/test-template.md 7 KB
- references/upstream-alignment.md 7 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · hugorcd/evlog | 95 | MIT |
| evloghq/evlog | 95 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki cf32953aeac2 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 95create-evlog-enricher
Tworzy nowy wbudowany enricher evlog dodający pochodny kontekst do szerokich zdarzeń, wraz z kodem, testami i dokumentacją. - 95create-evlog-map-rule
Dodaje nową regułę albo adapter frameworka do polecenia evlog map w @evlog/cli, razem z rejestrem, typami, testami i dokumentacją. - 95create-evlog-framework-integration
Tworzy integrację evlog z frameworkiem HTTP, dodając automatyczne logowanie zdarzeń przez middleware lub plugin, z testami i dokumentacją. - 100analyze-logs
Analizuje logi aplikacji z katalogu .evlog/logs/: błędy, wolne żądania i wzorce ruchu, na podstawie strukturalnych szerokich zdarzeń NDJSON zapisywanych przez evlog. - 100analyze-logs
Analizuje logi aplikacji z katalogu .evlog/logs w formacie NDJSON, przy debugowaniu błędów, wolnych żądań i wzorców zachowania aplikacji. - 100analyze-logs
Analizuje logi aplikacji z katalogu .evlog/logs w formacie NDJSON, przy debugowaniu błędów, wolnych żądań i wzorców zachowania aplikacji.