{
  "name": "log",
  "title": "Ravencraft Log Service",
  "version": "0.1.0",
  "base_url": "https://services.ravencraft.dk/log",
  "description": "Central event logging service for all services on services.ravencraft.dk",
  "auth": {
    "type": "api_key",
    "header": "X-API-Key",
    "keys": {
      "ingest": "ingest_api_keys",
      "read": "read_api_keys"
    }
  },
  "rate_limit": {
    "scope": "per_api_key_and_ip",
    "window": "1m",
    "limit_config_key": "services.log.rate_limit_per_minute",
    "behavior": "returns 429 when exceeded"
  },
  "endpoints": [
    {
      "method": "GET",
      "path": "/health.php",
      "returns": "application/json",
      "summary": "Service health check (includes DB connectivity).",
      "response_example": {
        "status": "UP",
        "service": "log",
        "version": "0.1.0",
        "time_utc": "2026-03-02T14:12:33Z",
        "db": "ok"
      }
    },
    {
      "method": "POST",
      "path": "/ingest.php",
      "consumes": "application/json",
      "returns": "application/json",
      "summary": "Ingest a single log event.",
      "request_schema": {
        "required": ["service", "level", "event"],
        "properties": {
          "service": { "type": "string", "maxLength": 64 },
          "env": { "type": "string", "maxLength": 16, "default": "prod" },
          "level": { "type": "string", "enum": ["debug", "info", "warn", "error"] },
          "event": { "type": "string", "maxLength": 128 },
          "message": { "type": ["string", "null"], "maxLength": 1024 },
          "request_id": { "type": ["string", "null"], "maxLength": 64 },
          "user_id": { "type": ["string", "null"], "maxLength": 64 },
          "tenant_id": { "type": ["string", "null"], "maxLength": 64 },
          "event_utc": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Optional event time. received_utc is always set by log service."
          },
          "meta": { "type": ["object", "array", "string", "number", "boolean", "null"] }
        }
      },
      "request_example": {
        "service": "placeholder",
        "level": "info",
        "event": "image.render",
        "message": "Rendered 128x128 icon",
        "request_id": "req-123",
        "tenant_id": "tenant-demo",
        "user_id": "user-42",
        "meta": { "w": 128, "h": 128, "format": "png" }
      },
      "response_example": {
        "status": "UP",
        "message": "logged",
        "id": 123,
        "received_utc": "2026-03-02T14:12:33Z"
      }
    },
    {
      "method": "GET",
      "path": "/recent.php",
      "returns": "text/html or application/json",
      "summary": "View recent logs (admin/dev).",
      "query_params": {
        "format": { "type": "string", "enum": ["html", "json"], "default": "html" },
        "limit": { "type": "integer", "min": 1, "max": 500, "default": 100 },
        "service": { "type": "string" },
        "level": { "type": "string", "enum": ["debug", "info", "warn", "error"] },
        "tenant_id": { "type": "string" }
      }
    }
  ],
  "storage": {
    "database": "MySQL/Percona",
    "tables": [
      "services_logs_events",
      "services_logs_ratelimit"
    ],
    "timestamps": {
      "received_utc": "set by log service",
      "event_utc": "optional from caller"
    }
  },
  "client": {
    "php_helper": "/shared/log_client.php",
    "function": "rc_log($CFG, $payload, $opts = [])"
  }
}