6. Signal definitions

Status	Stable
Version	2.0.0
Last updated	2026-01-31
Authors	OpenALBA Working Group

6.1 Overview

OpenALBA builds on OpenTelemetry semantic conventions to define the signals required for behavioral analytics. This section specifies both the raw attributes expected from instrumentation and the derived metrics computed by ALBA.

6.2 OpenTelemetry attributes

6.2.1 Required (Minimum Viable ALBA)

Required Attributesyaml

resource:
  service.name: "payment-api"           # Service profiling key
  service.version: "1.2.3"              # Deployment correlation
  deployment.environment.name: "prod"   # Environment multiplier

span:
  http.route: "/api/users/:id"          # Endpoint profiling (low cardinality)
  http.request.method: "GET"            # Method distribution
  http.response.status_code: 200        # Error calculation
  client.address: "203.0.113.42"        # Geographic analysis

Note

Implementations MUST support at least these attributes for minimum viable behavioral analytics. Without these, basic anomaly detection is not possible.

6.2.2 Recommended (Enhanced detection)

Recommended Attributesyaml

identity:
  user.id: "user-12345"                 # User profiling key
  session.id: "sess-abc123"             # Session analysis
  user.roles: ["admin", "developer"]    # Peer grouping
  enduser.scope: "read:users"           # Permission analysis

http_details:
  http.request.body.size: 1024          # Request anomalies
  http.response.body.size: 4096         # Exfiltration signals
  user_agent.original: "Mozilla/5.0..." # Bot detection

network:
  server.address: "api.stripe.com"      # Outbound tracking
  network.peer.address: "10.0.1.50"     # Lateral movement

6.2.3 Custom ALBA attributes

Beyond OpenTelemetry conventions, ALBA defines additional attributes for enhanced detection:

Custom ALBA Attributesyaml

authentication:
  auth.method: "oauth2"                 # Method distribution
  auth.result: "success|failure|mfa_required|locked_out"
  auth.failure_reason: "invalid_password|expired_token"
  auth.mfa_used: true

authorization:
  authz.decision: "permit|deny"
  authz.resource: "user:123:profile"
  authz.action: "read|write|delete"

data:
  data.sensitivity: "confidential"      # Sensitivity multiplier
  data.classification: ["PII", "PCI"]   # Data type tracking
  data.record_count: 100                # Bulk access detection

business:
  transaction.type: "purchase"
  transaction.value: 99.99
  customer.tier: "enterprise"

operations:
  deployment.change_id: "deploy-001"    # Deployment correlation
  feature_flag.active: ["new_checkout"] # Feature correlation

6.3 Derived metrics

ALBA computes derived metrics from raw observability data. These metrics form the basis for baseline establishment and anomaly detection.

6.3.1 Per-user metrics

Hourly aggregation, 90-day retention:

Per-User Metricsyaml

user.request_count: counter
user.unique_endpoints: gauge
user.unique_services: gauge
user.error_count: counter
user.error_rate: gauge (error_count/request_count)
user.response_bytes_total: counter
user.session_count: gauge
user.unique_client_ips: gauge
user.unique_countries: gauge
user.auth_failure_count: counter
user.sensitive_endpoint_access_count: counter
user.data_records_accessed: counter

6.3.2 Per-service metrics

Minutely aggregation, 30-day retention:

Per-Service Metricsyaml

service.request_rate: gauge (req/sec)
service.error_rate: gauge
service.latency_p50: gauge (ms)
service.latency_p95: gauge (ms)
service.latency_p99: gauge (ms)
service.unique_callers: gauge
service.outbound_call_count: counter
service.outbound_unique_destinations: gauge
service.outbound_error_rate: gauge

6.3.3 Per-endpoint metrics

Hourly aggregation, 30-day retention:

Per-Endpoint Metricsyaml

endpoint.request_count: counter
endpoint.unique_users: gauge
endpoint.unique_clients: gauge
endpoint.error_rate: gauge
endpoint.latency_p50: gauge
endpoint.latency_p99: gauge
endpoint.avg_response_size: gauge
endpoint.response_size_p99: gauge

6.3.4 Per-session metrics

Computed on session close, 90-day retention:

Per-Session Metricsyaml

session.duration_seconds: gauge
session.request_count: gauge
session.unique_endpoints: gauge
session.error_count: gauge
session.bytes_transferred: gauge
session.idle_time_total: gauge
session.navigation_depth: gauge

6.4 Cardinality management

High-cardinality fields require careful handling to avoid storage and performance issues:

Cardinality Managementyaml

high_cardinality_fields:
  - user.id
  - session.id
  - client.address
  - trace_id

strategies:
  pre_aggregation:
    "Count per user per hour, not store each request"

  tiered_retention:
    raw: 7 days
    hourly: 30 days
    daily: 365 days

  sampling:
    errors: 100%
    security_events: 100%
    slow_requests: 100%
    normal: 5%

  sketches:
    hyperloglog: "Unique counts, ~2% error"
    tdigest: "Percentiles"
    count_min_sketch: "Frequency"

  bucketing:
    client.address → country + asn

6.5 Conformance

Implementations:

MUST support required OpenTelemetry attributes
SHOULD support recommended attributes for enhanced detection
SHOULD implement per-user and per-service derived metrics
MUST implement cardinality management strategies for production deployments

Tip

Continue to Section 7: Detection Patterns for specific anomaly detection patterns.