Observability

Once your component is running, you need to see what it's doing. DevsPortal routes logs, metrics, and traces from every environment to the observability plane and surfaces them in the portal and the CLI — scoped to your component, so you don't go digging through cluster-wide dashboards.

note

DevsPortal is built on the Control Plane Operator engine. Telemetry flows to the observability plane, which exposes the Observer API at https://observer.idp.fedshi.com on the Fedshi instance. The occ CLI below is an unchanged engine internal.

Portal first, CLI second

The portal UI is the recommended path; the equivalent occ CLI commands follow for scripting.

Logs

In the portal

Open your component and select the Logs tab. You can:

• filter by environment (development, staging, production),
• narrow by time range, and
• search by keyword.

Logs are already scoped to your component — no label gymnastics required.

Or with the occ CLI

# Recent logs (auto-detects the lowest environment in the pipeline)
occ component logs cart-api -n fedshi -p checkout

# A specific environment
occ component logs cart-api --env production

# Follow live
occ component logs cart-api --env development -f

# Last 100 lines
occ component logs cart-api --env development --tail 100

# Only the last 30 minutes
occ component logs cart-api --env development --since 30m

--since accepts relative durations (5m, 1h, 24h); -f streams new lines as they arrive.

Metrics and alerts

When the observability plane is configured (it is, on Fedshi), additional tabs appear on the component:

• Metrics — request rate, latency, error rate, and resource graphs for your component.
• Alerts — alerts that have fired for your component.

Alerts come from traits your platform engineers (or you) attach. For example, the observability-alert-rule trait fires when a condition holds:

traits:
  - kind: ClusterTrait
    name: observability-alert-rule
    instanceName: high-error-rate
    parameters:
      enabled: true
      condition: "error_count > 100"

You can tune alert thresholds per environment through trait overrides — a noisier threshold in dev, a tighter one in prod. Notification channels (where alerts are delivered) are managed on the instance; see the operator Observability configuration.

Traces

Distributed traces flow to the same observability plane and are reachable through the Observer API. Use them to follow a single request as it crosses the components you wired together in Dependencies — for instance, a checkout request from the storefront into cart-api and on to its Postgres resource.

Inspecting the running pod

For anything the portal doesn't show, drop into the container itself:

# Interactive shell in the running pod
occ component exec cart-api -n fedshi -p checkout --env development -it

# Run a one-off command
occ component exec cart-api --env development -- curl -s localhost:8080/health

# Confirm injected dependency env vars
occ component exec cart-api --env development -it -- env | grep -E 'CART|DB_'

occ component exec defaults to /bin/sh and to the lowest environment if you omit --env. It requires the component:exec permission on your role — if it's denied, ask your team admin (see Roles and access).

Viewing Kubernetes artifacts

When you need to see the rendered resources behind a deployment, click View K8s Artifacts on an environment card in the console. It shows the resource tree — Deployments and ReplicaSets, Pods (with status and events), Services, HTTPRoutes, and cluster events. This is the fastest way to diagnose crash loops, image-pull errors, and routing problems without leaving the portal.

Common issues

Symptom	Likely cause	What to check
Component stuck in NotReady	Data-plane connectivity	Cluster agent pod logs on the data plane
Pods in CrashLoopBackOff	Application crashing on start	occ component logs; the Logs tab
Image pull error	Wrong image ref or missing registry credentials	Image reference; registry access on registry.idp.fedshi.com
No endpoint reachable	HTTPRoute missing or visibility too narrow	Endpoint visibility; View K8s Artifacts
No metrics/traces showing	Observability plane not reachable for that env	Confirm the env's observability plane with your platform engineer

What's next

• Deploy and promote — the deployment lifecycle these signals describe, including rollback.
• Dependencies — what those traces are crossing.
• Portal guide — where every tab lives in the console.