Product Specifications
Browse technical specifications and schemas
2 directories
File Tree
spec
conformance
cases
data.export.v1
passports
payments.refunds.v1
passports
integrations
oap
examples
vc
docs
json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "OAP Metrics Schema",
"description": "Observability and monitoring data schema for Open Agent Passport API",
"type": "object",
"required": ["timestamp", "service", "metrics"],
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when metrics were collected"
},
"service": {
"type": "string",
"description": "Service name generating the metrics",
"enum": ["aport-api", "aport-verify", "aport-policy", "aport-webhook"]
},
"version": {
"type": "string",
"description": "Service version",
"pattern": "^\\d+\\.\\d+\\.\\d+$"
},
"environment": {
"type": "string",
"enum": ["development", "staging", "production"],
"description": "Deployment environment"
},
"region": {
"type": "string",
"description": "Deployment region",
"enum": ["us", "eu", "ca", "ap", "global"]
},
"metrics": {
"type": "object",
"required": ["counters", "gauges", "histograms"],
"properties": {
"counters": {
"type": "object",
"description": "Monotonically increasing counters",
"properties": {
"requests_total": {
"type": "object",
"description": "Total number of requests",
"properties": {
"value": {
"type": "integer",
"minimum": 0
},
"labels": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"GET",
"POST",
"PUT",
"DELETE",
"PATCH",
"OPTIONS"
]
},
"endpoint": {
"type": "string"
},
"status_code": {
"type": "integer",
"minimum": 100,
"maximum": 599
},
"region": {
"type": "string"
}
}
}
}
},
"passports_created": {
"type": "object",
"description": "Total number of passports created",
"properties": {
"value": {
"type": "integer",
"minimum": 0
},
"labels": {
"type": "object",
"properties": {
"owner_type": {
"type": "string",
"enum": ["org", "user"]
},
"assurance_level": {
"type": "string",
"enum": ["L0", "L1", "L2", "L3", "L4KYC", "L4FIN"]
}
}
}
}
},
"decisions_created": {
"type": "object",
"description": "Total number of policy decisions created",
"properties": {
"value": {
"type": "integer",
"minimum": 0
},
"labels": {
"type": "object",
"properties": {
"policy_id": {
"type": "string"
},
"decision": {
"type": "string",
"enum": ["allow", "deny"]
},
"reason": {
"type": "string"
}
}
}
}
},
"errors_total": {
"type": "object",
"description": "Total number of errors",
"properties": {
"value": {
"type": "integer",
"minimum": 0
},
"labels": {
"type": "object",
"properties": {
"error_code": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"severity": {
"type": "string",
"enum": ["low", "medium", "high", "critical"]
}
}
}
}
}
}
},
"gauges": {
"type": "object",
"description": "Current values that can go up or down",
"properties": {
"active_passports": {
"type": "object",
"description": "Number of currently active passports",
"properties": {
"value": {
"type": "integer",
"minimum": 0
},
"labels": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["active", "suspended", "revoked"]
},
"region": {
"type": "string"
}
}
}
}
},
"active_connections": {
"type": "object",
"description": "Number of active connections",
"properties": {
"value": {
"type": "integer",
"minimum": 0
},
"labels": {
"type": "object",
"properties": {
"connection_type": {
"type": "string",
"enum": ["http", "websocket", "grpc"]
}
}
}
}
},
"memory_usage_bytes": {
"type": "object",
"description": "Current memory usage in bytes",
"properties": {
"value": {
"type": "integer",
"minimum": 0
}
}
},
"cpu_usage_percent": {
"type": "object",
"description": "Current CPU usage percentage",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 100
}
}
}
}
},
"histograms": {
"type": "object",
"description": "Distribution of values over time",
"properties": {
"request_duration_seconds": {
"type": "object",
"description": "Request duration distribution",
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"sum": {
"type": "number",
"minimum": 0
},
"buckets": {
"type": "object",
"description": "Histogram buckets",
"properties": {
"0.005": {
"type": "integer",
"minimum": 0
},
"0.01": {
"type": "integer",
"minimum": 0
},
"0.025": {
"type": "integer",
"minimum": 0
},
"0.05": {
"type": "integer",
"minimum": 0
},
"0.1": {
"type": "integer",
"minimum": 0
},
"0.25": {
"type": "integer",
"minimum": 0
},
"0.5": {
"type": "integer",
"minimum": 0
},
"1": {
"type": "integer",
"minimum": 0
},
"2.5": {
"type": "integer",
"minimum": 0
},
"5": {
"type": "integer",
"minimum": 0
},
"10": {
"type": "integer",
"minimum": 0
},
"+Inf": {
"type": "integer",
"minimum": 0
}
}
},
"labels": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"status_code": {
"type": "integer"
}
}
}
}
},
"policy_evaluation_duration_seconds": {
"type": "object",
"description": "Policy evaluation duration distribution",
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"sum": {
"type": "number",
"minimum": 0
},
"buckets": {
"type": "object",
"description": "Histogram buckets for policy evaluation"
},
"labels": {
"type": "object",
"properties": {
"policy_id": {
"type": "string"
},
"decision": {
"type": "string",
"enum": ["allow", "deny"]
}
}
}
}
}
}
}
}
},
"traces": {
"type": "array",
"description": "Distributed tracing data",
"items": {
"type": "object",
"properties": {
"trace_id": {
"type": "string",
"description": "Unique trace identifier"
},
"span_id": {
"type": "string",
"description": "Unique span identifier"
},
"parent_span_id": {
"type": "string",
"description": "Parent span identifier"
},
"operation_name": {
"type": "string",
"description": "Operation name"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Span start time"
},
"duration": {
"type": "number",
"description": "Span duration in seconds"
},
"tags": {
"type": "object",
"description": "Span tags",
"additionalProperties": {
"type": "string"
}
},
"logs": {
"type": "array",
"description": "Span logs",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time"
},
"fields": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
}
},
"events": {
"type": "array",
"description": "Application events",
"items": {
"type": "object",
"properties": {
"event_type": {
"type": "string",
"enum": [
"passport_created",
"passport_updated",
"passport_suspended",
"passport_revoked",
"decision_created",
"decision_updated",
"policy_evaluated",
"error_occurred",
"rate_limit_exceeded"
]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "object",
"description": "Event-specific data",
"additionalProperties": true
},
"severity": {
"type": "string",
"enum": ["debug", "info", "warn", "error", "fatal"]
}
}
}
}
},
"examples": [
{
"timestamp": "2025-01-16T10:30:00Z",
"service": "aport-api",
"version": "1.0.0",
"environment": "production",
"region": "us",
"metrics": {
"counters": {
"requests_total": {
"value": 1000000,
"labels": {
"method": "GET",
"endpoint": "/api/verify/{agent_id}",
"status_code": 200,
"region": "us"
}
},
"passports_created": {
"value": 5000,
"labels": {
"owner_type": "org",
"assurance_level": "L4KYC"
}
}
},
"gauges": {
"active_passports": {
"value": 2500,
"labels": {
"status": "active",
"region": "us"
}
},
"memory_usage_bytes": {
"value": 1073741824
}
},
"histograms": {
"request_duration_seconds": {
"count": 1000000,
"sum": 50000,
"buckets": {
"0.005": 100000,
"0.01": 200000,
"0.025": 300000,
"0.05": 400000,
"0.1": 500000,
"0.25": 600000,
"0.5": 700000,
"1": 800000,
"2.5": 900000,
"5": 950000,
"10": 990000,
"+Inf": 1000000
},
"labels": {
"method": "GET",
"endpoint": "/api/verify/{agent_id}",
"status_code": 200
}
}
}
}
}
]
}