Telemetry

AgeDigitalTwins supports real-time telemetry publishing that enables you to send time-series data and measurements from your digital twins to external systems. This functionality is designed to be compatible with Azure Digital Twins telemetry patterns while leveraging PostgreSQL's efficient NOTIFY/LISTEN mechanism.

Overview

Telemetry in AgeDigitalTwins provides:

• Real-time Publishing: Send telemetry data immediately without waiting for database commits
• Component-specific Telemetry: Publish telemetry for specific digital twin components
• Event Routing: Route telemetry events to configured sinks (Kafka, Azure Data Explorer, MQTT)
• Azure Digital Twins Compatibility: Uses the same API patterns as Azure Digital Twins
• High Performance: Built on PostgreSQL NOTIFY/LISTEN for minimal latency

How Telemetry Works

Telemetry in AgeDigitalTwins uses a different mechanism than lifecycle events:

1. Lifecycle Events (twin/relationship creation, updates, deletes) are captured through PostgreSQL logical replication
2. Telemetry Events are published directly through PostgreSQL NOTIFY/LISTEN for immediate delivery

This dual approach ensures:

• Lifecycle events are durable and replicated (important for maintaining state consistency)
• Telemetry events are delivered with minimal latency (important for real-time monitoring)

Publishing Telemetry

Basic Telemetry

Publish telemetry data for a digital twin:

// Publish basic telemetry
await client.PublishTelemetryAsync("sensor-001", new {
    temperature = 23.5,
    humidity = 45.2,
    timestamp = DateTime.UtcNow
});

Component Telemetry

Publish telemetry for a specific component within a digital twin:

// Publish component-specific telemetry
await client.PublishComponentTelemetryAsync("building-floor-2", "hvac-system", new {
    setPoint = 22.0,
    actualTemp = 23.1,
    energyUsage = 150.5,
    timestamp = DateTime.UtcNow
});

With Message ID

You can specify a custom message ID for tracking:

// Publish with custom message ID
await client.PublishTelemetryAsync("sensor-001", new {
    temperature = 23.5
}, messageId: "sensor-001-reading-12345");

Telemetry Event Format

Telemetry events follow the CloudEvents specification and are routed through the same event system as lifecycle events:

Basic Telemetry Event

{
  "specversion": "1.0",
  "type": "Konnektr.DigitalTwins.Telemetry",
  "source": "https://your-adt-instance/",
  "id": "12345678-1234-1234-1234-123456789012",
  "time": "2023-01-01T12:00:00Z",
  "datacontenttype": "application/json",
  "subject": "sensor-001",
  "data": {
    "temperature": 23.5,
    "humidity": 45.2,
    "timestamp": "2023-01-01T12:00:00Z"
  }
}

Component Telemetry Event

{
  "specversion": "1.0",
  "type": "Konnektr.DigitalTwins.Component.Telemetry",
  "source": "https://your-adt-instance/",
  "id": "12345678-1234-1234-1234-123456789012",
  "time": "2023-01-01T12:00:00Z",
  "datacontenttype": "application/json",
  "subject": "building-floor-2/components/hvac-system",
  "data": {
    "setPoint": 22.0,
    "actualTemp": 23.1,
    "energyUsage": 150.5,
    "timestamp": "2023-01-01T12:00:00Z"
  }
}

Event Routing for Telemetry

Telemetry events can be routed to the same sinks as lifecycle events. Configure telemetry routing in your event configuration:

eventRoutes:
  - eventType: Telemetry
    sink: InfluxDbSink
  - eventType: ComponentTelemetry
    sink: KafkaSink
  - eventType: Telemetry
    sink: MqttSink

Performance Considerations

High-Frequency Telemetry

For high-frequency telemetry data:

• Batch Publishing: Consider batching multiple telemetry points
• Component-based Routing: Route different components to different sinks
• Sink Selection: Use appropriate sinks for your data volume (e.g., InfluxDB for time-series, Kafka for real-time processing)

Event Processing

The telemetry system is designed for high throughput:

• Events are processed through a shared queue with batching
• Multiple event consumers can process telemetry concurrently
• PostgreSQL NOTIFY/LISTEN provides efficient event delivery
• Failed events don't block subsequent processing

Telemetry vs Lifecycle Events

Best Practices

Telemetry Design

1. Include Timestamps: Always include timestamp data in your telemetry payload
2. Use Component Telemetry: For complex twins, use component-specific telemetry for better organization
3. Consistent Schema: Maintain consistent telemetry schemas for easier downstream processing
4. Message IDs: Use meaningful message IDs for tracking and deduplication

Routing Strategy

1. Separate Sinks: Consider using different sinks for telemetry vs lifecycle events
2. Time-Series Databases: Route telemetry to time-series optimized databases (InfluxDB, TimescaleDB)
3. Real-time Processing: Use Kafka/Event Hubs for real-time telemetry processing
4. Monitoring: Set up monitoring for telemetry event volumes and processing rates

Integration Examples

IoT Sensor Integration

// Example: Regular sensor reading publication
public async Task PublishSensorReading(string twinId, SensorReading reading)
{
    await client.PublishTelemetryAsync(twinId, new {
        temperature = reading.Temperature,
        humidity = reading.Humidity,
        pressure = reading.Pressure,
        batteryLevel = reading.BatteryLevel,
        signalStrength = reading.SignalStrength,
        timestamp = reading.Timestamp
    });
}

HVAC System Monitoring

// Example: Component-based HVAC telemetry
public async Task PublishHvacTelemetry(string buildingId, HvacData hvac)
{
    await client.PublishComponentTelemetryAsync(buildingId, "hvac", new {
        setPointTemp = hvac.SetPoint,
        actualTemp = hvac.ActualTemperature,
        fanSpeed = hvac.FanSpeedPercent,
        energyConsumption = hvac.EnergyUsageKwh,
        mode = hvac.OperatingMode.ToString(),
        timestamp = DateTime.UtcNow
    });
}

See Also

• Event Routing - Learn about routing telemetry events to external systems
• Components - Understand digital twin components for component telemetry
• API Reference - Complete API documentation for telemetry methods