Monitoring

A persistent server (recyclarr serve or the Docker image) has two ports:

Port	Default	Serves
API	7982	The HTTP API and the API reference pages
Management	7983	Health probes (/livez, /readyz) and Prometheus metrics (/metrics)

Probes and metrics need no API key, and the server never serves them on the API port. You can publish only the API port through a reverse proxy, a Kubernetes Service, or an Ingress, and keep the management endpoints private. Probes and Prometheus reach the management port directly.

Set the port with server.management.port. It does not follow server.port, so changing the API port leaves the management port at 7983. The Docker image always uses 7983 inside the container. The management port listens on the same address as the API port (server.bind_address).

A temporary server, started by a CLI command, opens no management port.

Health Probes

GET /livez and GET /readyz both respond 200 with the plain text Healthy once the server listens. They do not check Sonarr or Radarr, so an unreachable instance never marks Recyclarr unhealthy.

The server opens no port at all until startup finishes. Startup includes database migrations and the first download of the TRaSH Guides, which can take several minutes on a slow connection. Give the first check enough time, for example with a Kubernetes startupProbe (see the example).

The Docker image has a built-in health check that uses /livez. See Health Check.

Prometheus Metrics

GET /metrics returns metrics in the Prometheus text format. Metrics are on by default; set server.management.metrics to false to turn them off.

The server reports:

• recyclarr.sync.job.duration: how long each sync job ran, in seconds, with the attributes recyclarr.sync.job.trigger (manual or scheduled) and recyclarr.sync.job.status (the job status it ended with)
• ASP.NET Core and Kestrel metrics for requests to the API port
• HttpClient metrics for requests to Sonarr, Radarr, and other services

Requests to the management port are not counted.

Logs

A persistent server writes its log to standard output. When that output is redirected, as it is in a container or a system service, each message is one JSON object per line for a log collector such as the container runtime or journald. Every server also writes log files by default. See server.logging for the format and file settings.

OpenTelemetry

When the OTEL_EXPORTER_OTLP_ENDPOINT environment variable is set, the server exports traces, metrics, and logs to that address over OTLP (the OpenTelemetry protocol). This works for any server, including a temporary one, as long as the variable is in its environment. Without it, the server sends no telemetry anywhere; /metrics still works.

Configure the export with the standard OpenTelemetry environment variables. Recyclarr has no settings of its own for it. Common ones:

Variable	Purpose
OTEL_EXPORTER_OTLP_ENDPOINT	Collector address. Turns the export on.
OTEL_EXPORTER_OTLP_PROTOCOL	grpc (default, usually port 4317) or http/protobuf (usually 4318)
OTEL_EXPORTER_OTLP_HEADERS	Headers to send, such as an authentication token
OTEL_SERVICE_NAME	Service name. Default: recyclarr-server
OTEL_RESOURCE_ATTRIBUTES	Extra resource attributes, such as deployment.environment=home

The export includes the same metrics as /metrics. Each sync job is its own trace. A job created by an API request, including one from a CLI command, links to the trace of that request. Scheduled jobs have no link. Health probes and metric scrapes produce no traces.

Kubernetes Example

This container publishes both ports, checks health on the management port, and exports telemetry to an OpenTelemetry Collector. Remove the two OTEL_* variables if you have no collector.

containers:
  - name: recyclarr
    image: ghcr.io/recyclarr/recyclarr:9
    ports:
      - name: http
        containerPort: 7982
      - name: management
        containerPort: 7983
    env:
      - name: RECYCLARR_API_KEY
        valueFrom:
          secretKeyRef:
            name: recyclarr
            key: api-key
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: http://otel-collector.monitoring:4317
      - name: OTEL_RESOURCE_ATTRIBUTES
        value: deployment.environment=home
    startupProbe:
      httpGet:
        path: /livez
        port: management
      periodSeconds: 10
      failureThreshold: 60 # allow up to 10 minutes for the first guide download
    livenessProbe:
      httpGet:
        path: /livez
        port: management
    readinessProbe:
      httpGet:
        path: /readyz
        port: management

Put only the http port in your Service. Prometheus scrapes /metrics from the pod's management port directly, for example with a PodMonitor. See Kubernetes for how to create the recyclarr Secret.

Kubernetes collects the container's JSON console output. If you do not also want log files in the volume, set server.logging.files to false in settings.yml.