Show table of contents Hide table of contents

Ingestion with HTTP

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-delimited 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"}