attune/docs/QUICKREF-sensor-action-env-parity.md

Quick Reference: Sensor vs Action Environment Variables

Last Updated: 2026-02-07
Status: Current Implementation

Overview

Both sensors and actions receive standard environment variables that provide execution context and API access. This document compares the environment variables provided to each to show the parity between the two execution models.

Side-by-Side Comparison

Purpose	Sensor Variable	Action Variable	Notes
Database ID	ATTUNE_SENSOR_ID	ATTUNE_EXEC_ID	Unique identifier in database
Reference Name	ATTUNE_SENSOR_REF	ATTUNE_ACTION	Human-readable ref (e.g., core.timer, core.http_request)
API Access Token	ATTUNE_API_TOKEN	ATTUNE_API_TOKEN	✅ Same variable name
API Base URL	ATTUNE_API_URL	ATTUNE_API_URL	✅ Same variable name
Triggering Rule	N/A	ATTUNE_RULE	Only for actions triggered by rules
Triggering Event	N/A	ATTUNE_TRIGGER	Only for actions triggered by events
Trigger Instances	ATTUNE_SENSOR_TRIGGERS	N/A	Sensor-specific: rules to monitor
Message Queue URL	ATTUNE_MQ_URL	N/A	Sensor-specific: for event publishing
MQ Exchange	ATTUNE_MQ_EXCHANGE	N/A	Sensor-specific: event destination
Log Level	ATTUNE_LOG_LEVEL	N/A	Sensor-specific: runtime logging config

Common Pattern: Identity and Context

Both sensors and actions follow the same pattern for identity and API access:

Identity Variables

• Database ID: Unique numeric identifier
  • Sensors: ATTUNE_SENSOR_ID
  • Actions: ATTUNE_EXEC_ID
• Reference Name: Human-readable pack.name format
  • Sensors: ATTUNE_SENSOR_REF
  • Actions: ATTUNE_ACTION

API Access Variables (Shared)

• ATTUNE_API_URL - Base URL for API calls
• ATTUNE_API_TOKEN - Authentication token

Sensor-Specific Variables

Sensors receive additional variables for their unique responsibilities:

Event Publishing

• ATTUNE_MQ_URL - RabbitMQ connection for publishing events
• ATTUNE_MQ_EXCHANGE - Exchange name for event routing

Monitoring Configuration

• ATTUNE_SENSOR_TRIGGERS - JSON array of trigger instances to monitor
• ATTUNE_LOG_LEVEL - Runtime logging verbosity

Example Sensor Environment

ATTUNE_SENSOR_ID=42
ATTUNE_SENSOR_REF=core.interval_timer_sensor
ATTUNE_API_URL=http://localhost:8080
ATTUNE_API_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGc...
ATTUNE_MQ_URL=amqp://localhost:5672
ATTUNE_MQ_EXCHANGE=attune.events
ATTUNE_SENSOR_TRIGGERS=[{"rule_id":1,"rule_ref":"core.timer_to_echo",...}]
ATTUNE_LOG_LEVEL=info

Action-Specific Variables

Actions receive additional context about their triggering source:

Execution Context

• ATTUNE_RULE - Rule that triggered this execution (if applicable)
• ATTUNE_TRIGGER - Trigger type that caused the event (if applicable)

Example Action Environment (Rule-Triggered)

ATTUNE_EXEC_ID=12345
ATTUNE_ACTION=core.http_request
ATTUNE_API_URL=http://localhost:8080
ATTUNE_API_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGc...
ATTUNE_RULE=monitoring.disk_space_alert
ATTUNE_TRIGGER=core.intervaltimer

Example Action Environment (Manual Execution)

ATTUNE_EXEC_ID=12346
ATTUNE_ACTION=core.echo
ATTUNE_API_URL=http://localhost:8080
ATTUNE_API_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGc...
# Note: ATTUNE_RULE and ATTUNE_TRIGGER not present for manual executions

Implementation Status

Fully Implemented ✅

• ✅ Sensor environment variables (all)
• ✅ Action identity variables (ATTUNE_EXEC_ID, ATTUNE_ACTION)
• ✅ Action API URL (ATTUNE_API_URL)
• ✅ Action rule/trigger context (ATTUNE_RULE, ATTUNE_TRIGGER)

Partially Implemented ⚠️

• ⚠️ Action API token (ATTUNE_API_TOKEN) - Currently set to empty string
  • Variable is present but token generation not yet implemented
  • TODO: Implement execution-scoped JWT token generation
  • See: work-summary/2026-02-07-env-var-standardization.md

Design Rationale

Why Similar Patterns?

1. Consistency: Developers can apply the same mental model to both sensors and actions
2. Tooling: Shared libraries and utilities can work with both
3. Documentation: Single set of patterns to learn and document
4. Testing: Common test patterns for environment setup

Why Different Variables?

1. Separation of Concerns: Sensors publish events; actions execute logic
2. Message Queue Access: Only sensors need direct MQ access for event publishing
3. Execution Context: Only actions need to know their triggering rule/event
4. Configuration: Sensors need runtime config (log level, trigger instances)

Usage Examples

Sensor Using Environment Variables

#!/bin/bash
# Sensor script example

echo "Starting sensor: $ATTUNE_SENSOR_REF (ID: $ATTUNE_SENSOR_ID)" >&2

# Parse trigger instances
TRIGGERS=$(echo "$ATTUNE_SENSOR_TRIGGERS" | jq -r '.')

# Monitor for events and publish to MQ
# (Typically sensors use language-specific libraries, not bash)

# When event occurs, publish to Attune API
curl -X POST "$ATTUNE_API_URL/api/v1/events" \
  -H "Authorization: Bearer $ATTUNE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_ref": "core.webhook",
    "payload": {...}
  }'

Action Using Environment Variables

#!/bin/bash
# Action script example

echo "Executing action: $ATTUNE_ACTION (ID: $ATTUNE_EXEC_ID)" >&2

if [ -n "$ATTUNE_RULE" ]; then
  echo "Triggered by rule: $ATTUNE_RULE" >&2
  echo "Trigger type: $ATTUNE_TRIGGER" >&2
else
  echo "Manual execution (no rule)" >&2
fi

# Read parameters from stdin (NOT environment variables)
INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message')

# Perform action logic
echo "Processing: $MESSAGE"

# Optional: Call API for additional data
EXEC_INFO=$(curl -s "$ATTUNE_API_URL/api/v1/executions/$ATTUNE_EXEC_ID" \
  -H "Authorization: Bearer $ATTUNE_API_TOKEN")

# Output result to stdout (structured JSON or text)
echo '{"status": "success", "message": "'"$MESSAGE"'"}'

Migration Notes

Previous Variable Names (Deprecated)

The following variable names were used in earlier versions and should be migrated:

Old Name	New Name	When to Migrate
ATTUNE_EXECUTION_ID	ATTUNE_EXEC_ID	Immediately
ATTUNE_ACTION_REF	ATTUNE_ACTION	Immediately
ATTUNE_ACTION_ID	(removed)	Not needed - use ATTUNE_EXEC_ID

Migration Script

If you have existing actions that reference old variable names:

# Replace in your action scripts
sed -i 's/ATTUNE_EXECUTION_ID/ATTUNE_EXEC_ID/g' *.sh
sed -i 's/ATTUNE_ACTION_REF/ATTUNE_ACTION/g' *.sh

See Also

• QUICKREF: Execution Environment Variables - Full action environment reference
• Sensor Interface Specification - Complete sensor environment details
• Worker Service Architecture - How workers set environment variables
• Sensor Service Architecture - How sensors are launched

References

• Implementation: crates/worker/src/executor.rs (action env vars)
• Implementation: crates/sensor/src/sensor_manager.rs (sensor env vars)
• Migration Summary: work-summary/2026-02-07-env-var-standardization.md