Developer Guide

Enforcing Log Schemas with the LogKit Schema Registry

Stop schema drift before it breaks your production observability. Learn how to define, publish, and enforce a single source of truth for your logs.

What is the Schema Registry?

In a distributed system, every service emits logs. Without a contract, those logs quickly diverge: a field changes name, a type becomes loose (string instead of int), or required context gets dropped. This is schema drift, and it turns a powerful observability tool into a debugging nightmare.

The LogKit Schema Registry solves this by acting as a central, versioned contract for your logs. It enforces type safety at the edge of your application, ensuring that every event emitted from your code matches the expected schema before it ever hits the network.

Why you need it

Eliminates Grep-and-Pray: Know exactly what fields exist for any event type.
Type Safety: Catch errors like sending a string "500" instead of an integer 500 at compile time.
Onboarding Speed: New engineers can query logs instantly because the structure is documented.

schema.json

{
  "version": "1.0.0",
  "name": "order_events",
  "fields": [
    {"name": "order_id", "type": "uuid", "required": true},
    {"name": "amount_usd", "type": "int", "required": true},
    {"name": "status", "type": "enum", "options": ["pending", "paid", "failed"]}
  ]
}

Defining a Schema

A schema is a JSON document that defines the shape of your events. It specifies field names, types, and whether a field is mandatory.

Field Types

Primitive Types

string: Free-form text
int / float: Numeric values
bool: Boolean state

Specialized Types

timestamp_iso8601: ISO 8601 dates
uuid: Unique identifiers
http_status_code: Standard HTTP codes

Required vs Optional

Mark fields as "required": true to enforce presence. If a log event is missing a required field, the SDK will block emission based on your enforcement mode.

schema.json

{
  "fields": [
    { "name": "user_id", "type": "uuid", "required": true }, // Must be present
    { "name": "session_id", "type": "uuid" } // Optional
  ]
}

Publishing and Assigning

Once defined, publish the schema to your LogKit workspace. Then, assign it to the specific service (or emitter) that will generate the logs.

Terminal

# 1. Publish the schema to the workspace
$ logkit schema publish --file schema.json --workspace "acme-backend"
✓ Schema "order_events" published as v1.0.0

# 2. Assign the schema to your api-service
$ logkit schema assign --schema "order_events" --service "api-service"
✓ Schema enforcement enabled for api-service

Enforcement Modes

How the platform reacts when a log event violates the schema contract.

Strict (Drop)

The log event is discarded immediately. The SDK returns an error to the calling code. This ensures 100% schema compliance but requires your application to handle the error.

Warn

The log is sent, but the SDK logs a warning to stderr. You retain the data for debugging but are alerted to the drift in your CI or logs.

Quarantine

The event is tagged with __logkit_schema_violation=true and sent to a separate "quarantine" stream. This allows you to analyze the bad data without breaking your dashboards.

Audit & Compliance

Schema Audit Reports

The LogKit console provides a real-time health score for every schema. View detailed audit reports that show:

How many logs were dropped due to schema violations.
Top offending fields causing errors.
Timeline of when a schema version was deployed.

View schema audit docs →

Versioning Schemas

LogKit supports Semantic Versioning (SemVer) for schemas. When you need to change a field, you must bump the version.

Backward-Compatible Changes (Minor/patch): Adding a new field, changing a type from int to float (if safe), or marking an optional field as required. Existing logs continue to work.

Breaking Changes (Major): Removing a field, changing a type from string to int, or deleting an option from an enum. The SDK will reject logs from services using the old schema version until they are updated.

CI Integration

Fail your build if code contains schema violations. Run the LogKit CLI in your pre-commit hooks or CI pipeline.

.github/workflows/ci.yml

name: Validate Logs
on: [pull_request]

jobs:
  schema-validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate schema compliance
        run: logkit schema validate --project acme-backend