Identifier-Safe Flexport Observability

Overview

Observe operations and reconciliation, not shipment contents. Build low-cardinality telemetry around surface, operation class, outcome, version, and queue health while keeping identifiers and payloads out.

Prerequisites

Approved metric labels and redaction rules
Operation taxonomy across OAuth, REST, MCP, webhook, and local processing
Business-defined service objectives and incident ownership

Instructions

Step 1: Define safe dimensions

Use environment, surface, operation class, status family, error class, version selection, and release. Exclude URLs with IDs, names, emails, routes, tags, documents, tokens, and raw messages.

Step 2: Measure auth health

Track cache hit, refresh success, token-request count, and credential alias as a controlled internal dimension; never log tokens or secret fragments.

Step 3: Measure reads and mutations separately

Record latency, attempts, pages, queue age, reconciliation lag, and ambiguous outcomes by operation class.

Step 4: Measure webhooks in stages

Distinguish received, signature-valid, durably queued, deduplicated, processed, and reconciled counts.

Step 5: Alert on objectives

Derive thresholds from approved freshness, queue, and error objectives—not arbitrary fixed seconds or undocumented rate headers.

Step 6: Audit telemetry

Sample schemas and label cardinality for sensitive leakage and regressions before expanding collection.

Authentication

REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.

Tool Discipline

Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.

Output

Scoped decision or implementation artifact
Redacted operation and validation receipt
Failure, rollback, and follow-up ownership record

Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:

surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
  release_sha: recorded-out-of-band
  provider_reference: redacted
rollback_owner: logistics-platform

Examples

A dashboard shows surface=mcp, operation=shipment-read, outcome, latency, and reconciliation lag. It never labels a series with FLEX-ID, route, company, email, or tool arguments.

Error Handling

Failure	Response
Identifier appears in labels	Drop or hash only under approved policy, then control cardinality.
Raw provider message contains data	Map to a safe error class and protect restricted details separately.
Alert has no business objective	Disable it until an owner defines the decision it drives.
Webhook counts diverge	Bound the window and run authenticated reconciliation.

flexport-observability