/prismatic-api-status

API L2+ Production medium usage

/prismatic-api-status

Overview

/prismatic-api-status is a production command in the API category of the Prismatic Platform that provides comprehensive health and operational status reporting for the auto-introspecting REST gateway. The command queries the running Prismatic API application to aggregate endpoint discovery statistics, scanner health, registry cache status, request throughput metrics, and error rates into a unified dashboard view.

The Prismatic API gateway is unique in that it discovers its own endpoints at boot time by introspecting all Prismatic* facade modules. This means the API surface is dynamic -- it changes as new modules are added or existing ones are modified. The status command provides visibility into this dynamic surface, reporting exactly how many modules were discovered, how many functions are exposed, and whether any modules failed introspection due to type mapping issues or missing documentation.

This command operates under the L2+ authority level and is executed by the elixir-core-specialist agent. It is part of the platform's 216-command slash command registry, built on the AIAD (Autonomous Intelligence Agent Design) standard. The command is used frequently during development and deployment cycles to verify that the API gateway is fully operational and that all expected endpoints are accessible.

Beyond simple health checks, the status command provides deep diagnostic information including per-endpoint latency percentiles, connection pool utilization, authentication success rates, and rate limiter state. This makes it an essential tool for both operational monitoring and troubleshooting API-related issues in production environments.

Architecture

The status command aggregates data from multiple subsystems within the API gateway architecture.

/prismatic-api-status
         |
         v
+------------------+
| StatusAggregator |
+------------------+
    |    |    |    |
    v    v    v    v
+------+ +------+ +------+ +------+
|Scanner| |Registry| |Router| |Telemetry|
|Health | |Stats  | |Metrics| |Events |
+------+ +------+ +------+ +------+
    |         |         |         |
    v         v         v         v
+-------------------------------------------+
|          Formatted Status Report          |
+-------------------------------------------+
ComponentData SourceMetrics Provided
ScannerPrismaticApi.ScannerModule count, scan duration, last scan timestamp
RegistryPrismaticApi.Registry (ETS)Endpoint count, cache hit rate, memory usage
RouterPrismaticApi.RouterActive routes, method distribution, path patterns
Telemetry:telemetry eventsRequest count, latency P50/P95/P99, error rates
AuthPrismaticWeb.Plugs.APIAuthAuth success/failure counts, token validity

Usage

Basic Status Check

# Quick status overview
/prismatic-api-status

# Detailed status with all metrics
/prismatic-api-status --verbose

# JSON output for programmatic consumption
/prismatic-api-status --format json

Health Monitoring

# Check if API is healthy (exit code 0 = healthy, 1 = unhealthy)
/prismatic-api-status --health-check

# Include endpoint-level health
/prismatic-api-status --endpoints

# Show only endpoints with errors
/prismatic-api-status --errors-only

Performance Metrics

# Display request latency percentiles
/prismatic-api-status --latency

# Show throughput over the last hour
/prismatic-api-status --throughput --window 1h

# Display connection pool utilization
/prismatic-api-status --connections

Diagnostic Mode

# Full diagnostic dump including internal state
/prismatic-api-status --diagnose

# Check for misconfigured or unreachable endpoints
/prismatic-api-status --check-endpoints

# Verify OpenAPI spec consistency with live endpoints
/prismatic-api-status --verify-spec

Options & Parameters

OptionTypeDefaultDescription
--verbosebooleanfalseInclude detailed metrics for all subsystems
--formatjson | text | tabletextOutput format for status report
--health-checkbooleanfalseSimple pass/fail health check with exit code
--endpointsbooleanfalseInclude per-endpoint status and metrics
--errors-onlybooleanfalseShow only endpoints or subsystems with errors
--latencybooleanfalseDisplay request latency percentiles (P50/P95/P99)
--throughputbooleanfalseDisplay request throughput statistics
--windowstring5mTime window for metric aggregation
--connectionsbooleanfalseShow connection pool utilization
--diagnosebooleanfalseFull diagnostic dump of internal state
--check-endpointsbooleanfalseVerify all endpoints are reachable
--verify-specbooleanfalseCompare live endpoints against OpenAPI spec

Execution Flow

The status command executes a multi-phase data collection and aggregation pipeline.

  1. Gateway Connectivity -- The command first verifies that the API gateway process is running and responsive. On port 4004, a lightweight health check endpoint (/api/v1/health) is pinged with a 5-second timeout.

  2. Scanner Status -- The Scanner GenServer is queried for its current state, including the number of discovered modules, the last scan timestamp, any scan errors, and the total scan duration.

  3. Registry Metrics -- ETS table statistics are collected from the endpoint registry, including total entries, memory consumption, and cache hit/miss ratios since the last restart.

  4. Request Metrics -- Telemetry event aggregations are retrieved for the specified time window. These include total request count, success/error breakdown, and latency distribution across percentiles.

  5. Authentication Metrics -- Auth plug statistics are collected, including token validation counts, expired token rejections, and unauthorized access attempts.

  6. Report Assembly -- All collected metrics are assembled into the requested output format and displayed. Exit codes are set based on overall health for script integration.

# Programmatic status check
{:ok, status} = PrismaticApi.Status.check()
# => %{healthy: true, endpoints: 47, uptime_seconds: 86400, ...}

Integration Points

SystemIntegrationPurpose
Prismatic APIPrimary target -- reports on this applicationStatus source
TelemetryConsumes [:prismatic_api, :request, :*] eventsMetrics source
Quality GatesAPI health as a quality gate prerequisiteGate input
CI/CD PipelineHealth check in deployment verificationDeployment gate
Prismatic WebAPI status widget on admin dashboardDisplay
Monitoring/AlertingStructured JSON output for log aggregationObservability
AIAD RegistryCommand registration and discoveryInfrastructure

Best Practices

  1. Post-deployment verification -- Always run /prismatic-api-status --check-endpoints after deploying changes to verify that all endpoints are accessible and responding correctly.

  2. Baseline establishment -- Capture a status snapshot before making changes with --format json to enable before/after comparison of endpoint counts and performance metrics.

  3. Monitoring integration -- Use --format json --health-check in monitoring scripts to feed structured health data into alerting systems. The command returns exit code 0 for healthy and 1 for unhealthy states.

  4. Regular spec verification -- Run --verify-spec periodically to detect drift between the live endpoint surface and the OpenAPI specification. Drift indicates that facade modules have changed without regenerating the spec.

  5. Window tuning -- Adjust --window based on traffic patterns. Use shorter windows (1m-5m) for real-time troubleshooting and longer windows (1h-24h) for trend analysis.

Error Handling

ErrorCauseResolution
{:error, :gateway_unreachable}API gateway process not running on port 4004Start the API application with mix phx.server
{:error, :scanner_not_running}Scanner GenServer has crashedCheck application supervisor tree and logs
{:error, :registry_empty}No endpoints discoveredVerify facade modules are compiled and loaded
{:error, :telemetry_unavailable}Telemetry system not initializedCheck telemetry handler registration in application startup
{:error, :timeout}Status collection exceeded timeoutIndividual subsystem may be overloaded; use --diagnose

When partial status collection succeeds, the command outputs available data and flags missing subsystems with [UNAVAILABLE] markers rather than failing entirely. This ensures operators always receive maximum available information.

Advanced Usage

Continuous Monitoring

# Watch status every 10 seconds
watch -n 10 '/prismatic-api-status --format text --latency'

# Stream status as JSON lines for log processing
while true; do /prismatic-api-status --format json; sleep 30; done | jq -c .

Programmatic Health Checks

# Use in deployment health check
defmodule MyApp.HealthCheck do
  def check_api do
    case PrismaticApi.Status.check() do
      {:ok, %{healthy: true}} -> :ok
      {:ok, %{healthy: false, errors: errors}} -> {:error, errors}
      {:error, reason} -> {:error, reason}
    end
  end
end

Comparison with Baseline

# Save baseline
/prismatic-api-status --format json > /tmp/api-baseline.json

# After changes, compare
/prismatic-api-status --format json > /tmp/api-current.json
diff <(jq -S . /tmp/api-baseline.json) <(jq -S . /tmp/api-current.json)

Doctrine Compliance

All commands operate under the NO MERCY, NO DOUBTS doctrine:

  • NO MERCY: Zero tolerance for incomplete execution or quality violations. The status command reports all subsystem states without omission. An unhealthy gateway is reported unambiguously with actionable diagnostic information.
  • NO DOUBTS: Full investigation before action, evidence-based results. Status data is collected directly from running processes and telemetry events, never estimated or cached beyond the specified window.

The command upholds NABLA Signal Plurality by aggregating status from multiple independent subsystems rather than relying on a single health indicator.

Connect & Contribute

Created by Tomáš Korcak (korczis) | Open Source under GHL

Related Commands

/prismatic-api-endpoints

List all auto-discovered API endpoints from facade modules

/prismatic-api-rescan

Trigger endpoint re-scan of all Prismatic facade modules

/prismatic-api-spec

Generate and view OpenAPI 3.0 specification
All Commands
Next
/prismatic-api-endpoints