plexctl route

Synopsis

plexctl route is the operator surface for the Telemetry Routes a Project holds. A route states one signal, the predicate that selects records on it, and the sinks that receive them. It wraps two /v1 surfaces under a single cobra parent:

• /v1/projects/{project_id}/telemetry-routes (create, list).
• /v1/telemetry-routes/{id} (get, update, delete).

A Project holds a bounded number of routes, so the collection is not paginated. A signal the Project routes nowhere falls back to the platform's own backends, and a route for a signal replaces that default rather than adding to it.

plexctl route <subcommand> [flags]

Subcommands

plexctl route create

POSTs /v1/projects/{project_id}/telemetry-routes. --project-id, --signal and at least one --sink-id are required: a route without a signal selects nothing, and one without a target delivers nowhere while still superseding the default.

Every target is checked when the route is written, so a route that would deliver nowhere is refused where it is authored. A --sink-id naming no sink fails with 422 route_sink_not_found; a tenant sink the Project holds no approved enablement for fails with 422 route_sink_not_usable; a sink whose type cannot receive the stated signal fails with 422 route_signal_not_accepted. A built-in sink needs no enablement, so it passes the second check by construction. Once the Project holds its maximum number of routes, a further create fails with 409 route_limit_reached.

plexctl route list

GETs /v1/projects/{project_id}/telemetry-routes (the --project-id flag is required). A Project that states no route reads back an empty list, which is a normal state rather than a refusal.

plexctl route get <id>

GETs /v1/telemetry-routes/{id}. The route is addressed by its own id, which does not encode the owning Project; the server reads the row and gates on the Project it belongs to.

plexctl route update <id>

PUTs /v1/telemetry-routes/{id} with the full post-image, so a field the command does not state is cleared rather than left untouched: an update that omits --severity-floor drops the stored floor. The owning Project is immutable and carries no flag, so the write applies against the Project the route already belongs to. Every target check the authoring path runs applies again.

plexctl route delete <id>

DELETEs /v1/telemetry-routes/{id}. Requires --yes. Deleting a route puts its signal back on the platform's own backends, so the confirmation is fail-closed and decided locally.

Signals and predicates

--signal names the stream the route governs: logs, metrics or audit. The three are independent and a route governs exactly one.

The two predicate flags belong to one signal each, and the server enforces the pairing:

• --severity-floor states the least severe log keyword the route still carries, and belongs to a logs route. The roster runs most severe first: emerg, alert, crit, err, warning, notice, info, debug. A floor of warning carries warning and everything more severe.
• --name-prefix states the leading characters of the metric series names the route selects, and belongs to a metrics route. It is at most 256 runes.

A predicate stated on a signal that does not define one is refused with 422 telemetry_route_invalid naming the field, rather than carried along and ignored at delivery time. Both flags are passed to the server verbatim: the pairing rule and the keyword roster have one authority, and a local membership check would go stale the day another signal is added.

Flags

plexctl route create

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.
--signal	string	yes	Stream the route governs: logs, metrics or audit.
--sink-id	UUID	yes	Sink UUID to deliver to. Repeatable, at least once.
--severity-floor	string	no	Least severe log keyword to carry. Logs routes only.
--name-prefix	string	no	Leading characters of the metric names to select. Metrics routes only.

plexctl route list

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.

plexctl route update <id>

Takes the same field flags as plexctl route create minus --project-id, which addresses immutable state. --signal and --sink-id stay required, because the body is the full post-image.

plexctl route delete <id>

Flag	Type	Required	Description
--yes (persistent)	bool	yes	Required confirmation for the destructive operation.

Destructive subcommands

plexctl route delete consumes the persistent --yes flag. It rejects the call without explicit confirmation, and the refusal is decided locally with exit 2 before any request is sent.

Persistent flags inherited from root

--server, --profile, --token-file, --output, --yes, --reveal-secrets. See ../plexctl.md.

Exit codes

See ../plexctl.md#exit-code-taxonomy.

Examples

Route warning-and-above logs to two sinks

plexctl route create \
  --server         "${PLEXSPHERE_URL}" \
  --project-id     0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --signal         logs \
  --severity-floor warning \
  --sink-id        0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e0 \
  --sink-id        0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e1

Narrow a metrics route to one series prefix

plexctl route update 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0f0 \
  --server      "${PLEXSPHERE_URL}" \
  --signal      metrics \
  --name-prefix plexsphere_ \
  --sink-id     0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e0

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml
• ../../../cmd/plexctl/commands/route.go
• ../../api/sinks.md
• sink.md, the sinks a route targets and the enablement a tenant sink needs.
• ../../../contexts/observability/routes.md, ../../../contexts/observability/routing.md