Ingestion with HTTP
Events can be sent directly to the Seq API by posting JSON via HTTP/S
In some situations it may be desirable to send events to Seq without using a telemetry library like Serilog or OpenTelemetry. In that case, batches of events can be sent in newline-delimited JSON format directly to Seq's HTTP API.
Compact JSON format
Events are POSTed to the /ingest/clef endpoint:
POST https://localhost:5341/ingest/clef
The /ingest/clef endpoint accepts compact JSON format (CLEF) payloads.
If an API key is required, it can be specified as ?apiKey= in the URL, or sent in the X-Seq-ApiKey HTTP header.
To identify the payload as compact log event format, specify the value application/vnd.serilog.clef in the ContentType header. Single events may be sent with the application/json content type.
The CLEF format
Batches of events in this format are newline-separated JSON documents:
{"@t":"2016-06-07T03:44:57.8532799Z","@mt":"Hello, {User}","User":"alice"}
{"@t":"2016-06-07T04:10:00.3457981Z","@mt":"Hello, {User}","User":"bob"}
Each event is a JSON object with event data at the top level. Any JSON property on the payload object is assumed to be a regular property of the event, apart from the reified properties below.
Reified properties
The format defines a handful of properties that have special meaning.
| Property | Name | Description | Required? |
|---|---|---|---|
@t | Timestamp | An ISO 8601 timestamp | Yes |
@m | Message | A fully-rendered message describing the event | |
@mt | Message template | Alternative to @m; specifies a message template over the event's properties that provides for rendering into a textual description of the event | |
@l | Level | An implementation-specific level identifier; Seq requires a string value if present | Absence implies "informational" |
@x | Exception | A language-dependent error representation potentially including backtrace; Seq requires a string value, if present | |
@i | Event id | An implementation-specific event id; Seq uses this field for the event type, and accepts either numeric or hexadecimal string values. | |
@r | Renderings | If @mt includes tokens with programming-language-specific formatting, an array of pre-rendered values for each such token | May be omitted; if present, the count of renderings must match the count of formatted tokens exactly |
@tr | Trace id | An identifier that groups all spans and logs that are in the same trace | Yes, if the event is a span |
@sp | Span id | Unique identifier of a span | Yes, if the event is a span |
@ps | Parent id | The span id of this span's parent; absence indicates that this is the root span of a trace | |
@st | Start | The start ISO 8601 timestamp of this span | Yes, if the event is a span |
@sc | Instrumentation scope | Describes the application-local component responsible for the event | |
@ra | Resource attributes | Describes the system-level component responsible for the event | |
@sk | Span kind | Describes the relationship of the span to others in the trace: Client, Server, Internal, Producer, or Consumer |
The @ sigil may be escaped at the start of a user property name by doubling, e.g. @@name denotes a property called @name.
Except for @mt, property names with two characters, such as @tr, are later extensions to the original, minimal CLEF specification that may not be recognized by other systems.
Batch format
When events are batched into a single payload, a newline-delimited stream of JSON documents is required. Either \n or \r\n delimiters may be used. Batches of newline-separated compact JSON events can use the (unofficial) MIME type application/vnd.serilog.clef.
Status codes and response format
The POST request will return one of the following status codes:
| Status code | Meaning |
|---|---|
| 201 Created | The events were ingested successfully |
| 400 Bad Request | The request was malformed; sometimes this indicates incorrect payload formatting, or more frequently, an included event exceeds the configured maximum event size |
| 401 Unauthorized | Authorization is required; this status code may be returned if an API key is missing or invalid |
| 403 Forbidden | The provided credentials don't have ingestion permission |
| 413 Request Entity Too Large | The payload itself exceeds the configured maximum size |
| 500 Internal Server Error | An internal error prevented the events from being ingested; check Seq's diagnostic log for more information |
| 503 Service Unavailable | The Seq server is starting up and can't currently service the request, or, free storage space has fallen below the minimum required threshold; this status code may also be returned by HTTP proxies and other network infrastructure when Seq is unreachable |
If the status code indicates success, the response will be of the form:
{"MinimumLevelAccepted": null}
The MinimumLevelAccepted value will be null if no level filter is applied, and one of the Serilog level values Verbose, Debug, Information, Warning, Error and Fatal if filtering is applied. The client may use these values to pre-filter events and therefore reduce network bandwidth utilization.
If the status code indicates failure, the response will be of the form:
{"Error": "This is an error message"}
Classic format
Versions of Seq prior to 3.3 only accept the classic payload format, which takes the form of a single JSON document
POSTed to/api/events/raw. See the earlier versions of this documentation for details.
Updated 4 months ago