Installing the console

Operations guide: configure, deploy and observe the gateway. What the feature does, product side: product guide; calling it: developer guide.

The console is deployed apart from the gateway (its own binary, image and chart). One mode for metrics and traces: your backends, or the console as the gateway's OTLP collector; never a mix, refused at render. What it shows: Reading with the console.

Steps

Try it locally

Every screen has data within minutes: the stack's demonstration traffic goes through the gateway's API, never into a store.

Install in a cluster

1. Choose the mode and install the chart, without any identity provider:

   # With your backends: the console reads your Prometheus, links to your traces,
   # receives nothing and stores nothing
   helm install console oci://ghcr.io/flexwiz/charts/flexway-console --version <version> \
     --set gateway.url=http://orders-flexway-admin:9090 --set metrics.url=http://victoriametrics:8428 \
     --set traces.url='https://grafana.example/explore?traceId={trace_id}'
   
   # Without any backend: the gateway pushes metrics and traces to the console (OTLP, TLS, mutual TLS
   # by default), which keeps the history on a persistent volume per replica (8 GiB by default)
   helm install console oci://ghcr.io/flexwiz/charts/flexway-console --version <version> \
     --set gateway.url=http://orders-flexway-admin:9090 --set persistence.size=8Gi \
     --set otlp.tls.issuerRef.name=flexway-ca --set 'otlp.tls.clientNames={orders-flexway.observability.svc}'

2. Without a backend, make the gateway push to the console (the gateway's values), and set TLS on the console's side:

   values.yaml

   # The console's values: TLS is required, mutual TLS by default (cert-manager, a CA Issuer)
   otlp:
     tls:
       issuerRef: { name: flexway-ca }                     # a Certificate is rendered for the console
       clientNames: [orders-flexway.observability.svc]     # the name of the gateway's certificate
     # meshEncrypted: true                  # only where a mesh already encrypts (Linkerd, strict Istio)
   # The gateway's values:
   tracesToConsole:
     enabled: true
     endpoint: https://console-flexway-console-otlp.observability:4317
     tls: { issuerRef: { name: flexway-ca } }   # renders its client certificate orders-flexway.observability.svc

3. With your backends, write their addresses in the values; the trace link takes any tool reachable by URL:

   values.yaml

   # values.yaml of the services/console/deploy/helm chart
   gateway: { url: "http://orders-flexway-admin:9090" }      # the admin surface
   metrics: { url: "http://victoriametrics:8428" }           # a Prometheus API
   # Grafana Explore on Tempo; any trace tool reachable by URL works:
   # {operation}, {client} (the agent), {start_us}/{end_us} (microseconds), {start_ms}/{end_ms} (milliseconds)
   traces:  { url: "https://grafana.example/explore?schemaVersion=1&orgId=1&panes=%7B%22a%22%3A%7B%22datasource%22%3A%22tempo%22%2C%22queries%22%3A%5B%7B%22refId%22%3A%22A%22%2C%22datasource%22%3A%7B%22type%22%3A%22tempo%22%2C%22uid%22%3A%22tempo%22%7D%2C%22queryType%22%3A%22traceql%22%2C%22query%22%3A%22%7Bresource.service.name%3D%5C%22flexway%5C%22%20%26%26%20span.operation_id%3D%5C%22{operation}%5C%22%7D%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22{start_ms}%22%2C%22to%22%3A%22{end_ms}%22%7D%7D%7D" }

4. Sign in as the first admin and invite the other accounts: Accounts and identity provider.

Retention

Without a backend: 35 days of detail (retention.detail, adjustable), daily aggregates - requests, errors, tokens, euros - over 13 months (retention.daily) to compare month over month and year over year; a persistent volume is required (the render is refused with persistence.enabled: false), filled to 80 % at most, the oldest data going first. Past 35 days, plan 10 GiB at least; further still, your Prometheus.

Verify

1. A strip at the top of Overview, Traffic, Upstreams, Catalogue and Usage says the source and the retention; its "Details" panel shows the replicas sending, the last export received and the volume (to admins).
2. Each gateway replica shows on the Overview's map, under its pod name (service.instance.id); a replica silent for 45 s turns unknown.
3. Diagnostics -> Errors lists each replica's errors, read through the gateway's headless Service (orders-flexway-admin-headless).

Good to know

• With several console replicas and no backend, the one that receives an export relays it to the others (bounded queue, retries): each keeps a full copy; a replica back asks another for the last two hours.
• Switching mode = uninstall then install again: the state Secret and its accounts are kept.
• With traces.url (and metrics.url), the console's OTLP receiver stays off.
• What the console keeps of a trace: a whitelist's attributes (operation_id, upstream, tenant, policies, status, the contract's method and route), everything else dropped at reception - an address, a header or a body cannot get in. A request the gateway's head sampling (observability.sampling.max_per_second) did not retain never arrives; every error stays in the error journal.
• With your own backend, the collector must keep service.instance.id in the instance label (Alloy and Prometheus' OTLP write do by default): without it, a single "replica" is seen.

Available since 0.1.0; without a backend, the console as OTLP collector since 1.3.0.