logdistributor

Log Distributor System API Documentation

This document describes the HTTP API exposed by both services in the project:

Analyser API – a FastAPI application processing log packets.
Distributor API – an Akka HTTP service responsible for routing packets to registered analysers.

All endpoints accept and return application/json unless noted otherwise.

Analyser API

Base URL: depends on deployment. In development it listens on port 8000.

Models

`LogMessage`

{
  "level": "INFO",      // log level
  "message": "text"      // log message
}

`LogPacket`

{
  "id": "string",        // unique identifier for the packet
  "timestamp": 1700000000000,  // Unix epoch millis
  "messages": [LogMessage, ...]
}

Endpoints

Method & Path	Description
`POST /analyse`	Submit a log packet for processing.
`GET /heartbeat`	Health probe. Returns analyser status.
`GET /custom_metrics`	Current packet/message counters.
`GET /metrics`	Prometheus metrics endpoint.
`POST /internal/simulate/fail`	Mark analyser as unhealthy.
`POST /internal/simulate/begin`	Mark analyser as healthy.

`POST /analyse`

Request body: LogPacket

Response:

{
  "id": "<packet id>"
}

`GET /heartbeat`

Response:

{
  "alive": true
}

`GET /custom_metrics`

Response example:

{
  "packets": 42,
  "messages": 123,
  "alive": true,
  "app": "fastapi_analyser"
}

The /metrics endpoint exposes the default and custom Prometheus metrics.

The /internal/simulate/fail and /internal/simulate/begin endpoints are primarily for testing the health‑check mechanism.

Distributor API

Base URL: by default http://localhost:8080.

Models

`LogMessage`

Same as in the Analyser API.

`LogPacket`

Same as in the Analyser API.

`Analyser`

{
  "uuid": "string",           // unique analyser identifier
  "name": "string",           // human readable name
  "url": "http://host:port",  // analyser base URL
  "weight": 1.0               // relative load balancing weight
}

Endpoints

Method & Path	Description
`GET /health`	Simple health check endpoint.
`POST /distributor/packet`	Enqueue a log packet for distribution.
`POST /distributor/analyser`	Register a new analyser instance.
`GET /distributor/analyser`	List all currently registered analysers.

`POST /distributor/packet`

Request body: LogPacket

Response codes:

200 OK – packet was accepted.
500 Internal Server Error – processing failed.

`POST /distributor/analyser`

Request body: Analyser

Response codes:

200 OK – analyser registered.
500 Internal Server Error – registration failed.

`GET /distributor/analyser`

Returns an array of Analyser objects.

Example

curl -XPOST http://localhost:8080/distributor/analyser \
     -H "Content-Type: application/json" \
     -d '{"uuid":"a1","name":"Analyser-1","url":"http://analyser:8000","weight":1.0}'

curl -XPOST http://localhost:8080/distributor/packet \
     -H "Content-Type: application/json" \
     -d '{"id":"p1","timestamp":1700000,"messages":[{"level":"INFO","message":"demo"}]}'