openapi: 3.0.3
info:
  title: StatsD Admin Interface Configuration Stats API
  version: 1.0.0
  description: OpenAPI projection of the StatsD admin/management interface. The native transport is a line-oriented plain-text protocol over TCP/8126 (default), not HTTP — but every supported command (`stats`, `counters`, `gauges`, `timers`, `delcounters`, `delgauges`, `deltimers`, `health [up|down]`, `config`, `quit`) is a self-contained request/response interaction with well-defined inputs and outputs and is therefore modeled here as a virtual `GET`/`POST` resource so that tools that consume OpenAPI (Spectral, MCP adapters, client generators) can reason about the surface.
  contact:
    name: StatsD Maintainers
    url: https://github.com/statsd/statsd
  license:
    name: MIT
    url: https://github.com/statsd/statsd/blob/master/LICENSE
servers:
- url: tcp://{host}:{port}
  description: Native admin TCP interface
  variables:
    host:
      default: 127.0.0.1
      description: Address of the StatsD daemon
    port:
      default: '8126'
      description: Default admin port (`mgmt_port`)
tags:
- name: Stats
  description: Inspect Aggregated In-Memory State
paths:
  /stats:
    get:
      summary: Get Server Stats
      description: Return the daemon's own self-stats — uptime in seconds, `messages.last_msg_seen` in seconds since the last metric was received, and `messages.bad_lines_seen` since startup. Backends append their own keys (e.g., `graphite.last_flush`, `graphite.flush_time`).
      operationId: getStats
      tags:
      - Stats
      responses:
        '200':
          description: Plain-Text Stats Block, Terminated By `END`.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/AdminStatsResponse'
components:
  schemas:
    AdminStatsResponse:
      type: object
      description: Self-stats returned by the `stats` command.
      properties:
        uptime:
          type: integer
          description: Seconds since the daemon started.
        messages.last_msg_seen:
          type: integer
          description: Seconds since the most recent metric line was received.
        messages.bad_lines_seen:
          type: integer
          description: Number of unparseable metric lines since startup.
        graphite.last_flush:
          type: integer
          description: Seconds since the last Graphite flush (Graphite backend only).
        graphite.last_exception:
          type: integer
          description: Seconds since the last Graphite flush exception.
        graphite.flush_length:
          type: integer
          description: Bytes written in the last Graphite flush.
        graphite.flush_time:
          type: integer
          description: Milliseconds spent in the last Graphite flush.