55da2b74a4
Add a comprehensive skill for interacting with the Seq HTTP API, covering event ingestion (CLEF/OpenTelemetry), querying, API key management, signals, dashboards, alerts, diagnostics, backups, and user management. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
145 lines
5.2 KiB
Markdown
145 lines
5.2 KiB
Markdown
# Seq Ingestion Reference — CLEF Format & HTTP Details
|
|
|
|
## Endpoint
|
|
|
|
```
|
|
POST {SEQ_URL}/ingest/clef
|
|
```
|
|
|
|
## Headers
|
|
|
|
| Header | Value | Required |
|
|
|--------|-------|----------|
|
|
| `Content-Type` | `application/vnd.serilog.clef` (batch) or `application/json` (single event) | Yes |
|
|
| `X-Seq-ApiKey` | Your API key | Only if `RequireApiKeyForWritingEvents` is enabled |
|
|
|
|
Alternatively, the API key can be passed as a query parameter: `?apiKey={key}`
|
|
|
|
## CLEF Format
|
|
|
|
Events are newline-delimited JSON documents (one JSON object per line). Each object represents one log event.
|
|
|
|
### Batch Example
|
|
|
|
```
|
|
{"@t":"2024-01-15T10:30:00.000Z","@mt":"Hello, {User}","User":"alice"}
|
|
{"@t":"2024-01-15T10:30:01.123Z","@mt":"Processing order {OrderId}","OrderId":42,"@l":"Information"}
|
|
{"@t":"2024-01-15T10:30:02.456Z","@mt":"Failed to process {OrderId}","OrderId":42,"@l":"Error","@x":"System.Exception: Something went wrong\n at MyApp.OrderProcessor.Process()"}
|
|
```
|
|
|
|
### Reified Properties (Special @ Properties)
|
|
|
|
Any JSON property at the top level is treated as a regular event property, **except** the following special properties:
|
|
|
|
| Property | Name | Description | Required? |
|
|
|----------|------|-------------|-----------|
|
|
| `@t` | Timestamp | ISO 8601 timestamp | **Yes** |
|
|
| `@m` | Message | Fully-rendered message text | No (use `@mt` or `@m`) |
|
|
| `@mt` | Message Template | [Message template](http://messagetemplates.org) with named holes like `{User}` | No (alternative to `@m`) |
|
|
| `@l` | Level | Log level string: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal` | No (defaults to Information) |
|
|
| `@x` | Exception | Error/backtrace as a string | No |
|
|
| `@i` | Event ID | Event type identifier (numeric or hex string) | No |
|
|
| `@r` | Renderings | Pre-rendered values for format tokens in `@mt` | No |
|
|
| `@tr` | Trace ID | Groups spans/logs in the same trace | Required for spans |
|
|
| `@sp` | Span ID | Unique span identifier | Required for spans |
|
|
| `@ps` | Parent Span ID | Parent span's ID; absent = root span | No |
|
|
| `@st` | Span Start | ISO 8601 start timestamp of the span | Required for spans |
|
|
| `@sc` | Instrumentation Scope | App-local component name | No |
|
|
| `@ra` | Resource Attributes | System-level component descriptor | No |
|
|
| `@sk` | Span Kind | `Client`, `Server`, `Internal`, `Producer`, or `Consumer` | No |
|
|
|
|
### Escaping @ in Property Names
|
|
|
|
To use a property name starting with `@`, double it: `@@myProp` becomes `@myProp` in Seq.
|
|
|
|
### Batch Delimiters
|
|
|
|
Use `\n` or `\r\n` between JSON objects. No trailing delimiter is required but is harmless.
|
|
|
|
## Status Codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| **201** Created | Events ingested successfully |
|
|
| **400** Bad Request | Malformed payload or event exceeds max size |
|
|
| **401** Unauthorized | API key missing or invalid |
|
|
| **403** Forbidden | API key lacks Ingest permission |
|
|
| **413** Request Entity Too Large | Payload exceeds configured max size |
|
|
| **500** Internal Server Error | Server-side error; check Seq diagnostics |
|
|
| **503** Service Unavailable | Server starting up, or storage space below threshold |
|
|
|
|
## Response Format
|
|
|
|
### Success (201)
|
|
|
|
```json
|
|
{"MinimumLevelAccepted": null}
|
|
```
|
|
|
|
`MinimumLevelAccepted` will be one of `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal` if a level filter is applied to the API key, or `null` if no filtering. Clients can use this to pre-filter events and reduce bandwidth.
|
|
|
|
### Error (4xx/5xx)
|
|
|
|
```json
|
|
{"Error": "Description of what went wrong"}
|
|
```
|
|
|
|
## OpenTelemetry Ingestion
|
|
|
|
Seq also accepts OpenTelemetry Protocol (OTLP) payloads:
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `ingest/otlp/v1/logs` | OTLP logs |
|
|
| `ingest/otlp/v1/traces` | OTLP traces |
|
|
| `ingest/otlp/v1/metrics` | OTLP metrics |
|
|
|
|
These follow the standard OTLP HTTP specification. The same API key authentication rules apply.
|
|
|
|
## Raw Events Endpoint (Legacy)
|
|
|
|
The older `api/events/raw` endpoint also accepts event ingestion with cross-site POST support. The `/ingest/clef` endpoint is preferred for new integrations.
|
|
|
|
## Common curl Examples
|
|
|
|
### Send a single event
|
|
|
|
```bash
|
|
curl -X POST "https://seq.example.com/ingest/clef" \
|
|
-H "Content-Type: application/vnd.serilog.clef" \
|
|
-H "X-Seq-ApiKey: YOUR_API_KEY" \
|
|
-d '{"@t":"2024-01-15T10:30:00Z","@mt":"Deployment started for {App}","App":"myservice","@l":"Information"}'
|
|
```
|
|
|
|
### Send a batch
|
|
|
|
```bash
|
|
curl -X POST "https://seq.example.com/ingest/clef" \
|
|
-H "Content-Type: application/vnd.serilog.clef" \
|
|
-H "X-Seq-ApiKey: YOUR_API_KEY" \
|
|
-d '{"@t":"2024-01-15T10:30:00Z","@mt":"Step 1 complete","@l":"Information"}
|
|
{"@t":"2024-01-15T10:30:01Z","@mt":"Step 2 complete","@l":"Information"}
|
|
{"@t":"2024-01-15T10:30:02Z","@mt":"All steps done","@l":"Information"}'
|
|
```
|
|
|
|
### Send with an API key in the query string
|
|
|
|
```bash
|
|
curl -X POST "https://seq.example.com/ingest/clef?apiKey=YOUR_API_KEY" \
|
|
-H "Content-Type: application/vnd.serilog.clef" \
|
|
-d '{"@t":"2024-01-15T10:30:00Z","@mt":"Hello from curl"}'
|
|
```
|
|
|
|
### Query events via the data API
|
|
|
|
```bash
|
|
curl "https://seq.example.com/api/data?q=select%20count(*)%20from%20stream%20group%20by%20%40Level&rangeStartUtc=2024-01-01&rangeEndUtc=2024-01-02" \
|
|
-H "X-Seq-ApiKey: YOUR_API_KEY"
|
|
```
|
|
|
|
### Check server health
|
|
|
|
```bash
|
|
curl https://seq.example.com/health
|
|
```
|