Sources

Understanding event sources and how to properly identify the origin of events in your system.

What is an Event Source?

An event source identifies where an event originated from. It provides context about which component, service, or system generated the event. This is crucial for debugging, tracing, and understanding the flow of events through your system.

The source is typically represented as a URI or identifier that uniquely identifies the producer of the event. It should be detailed enough to trace back to the specific instance or component that generated the event.

Example: https://api.example.com/orders/service

Microservice Sources

Events originating from specific microservices in your architecture.

Example Sources:
/services/order-service
/services/payment-service
/services/inventory-service
/services/notification-service

Include service name, version, and optionally instance ID for precise tracking.

Web Application Sources

Events generated by web applications or API endpoints.

Example Sources:
https://app.example.com
https://api.example.com/v1
https://admin.example.com

Use full URLs to identify the specific application or API version.

Mobile App Sources

Events from mobile applications on different platforms.

Example Sources:
com.example.app.ios/v2.1.0
com.example.app.android/v2.1.0
com.example.tablet/v1.5.0

Include platform and version information for mobile sources.

System Sources

Events from background jobs, scheduled tasks, or system processes.

Example Sources:
/jobs/daily-report-generator
/cron/cleanup-task
/workers/email-processor
/batch/invoice-generator

Clearly identify automated processes and scheduled tasks.

Source URI Formats

Sources are commonly expressed as URIs to provide a standardized way of identifying the origin. Different formats can be used depending on your needs:

HTTP/HTTPS URLs

https://api.example.com/orders/v1

Best for web services and REST APIs. Includes protocol, domain, and path.

URN (Uniform Resource Name)

urn:example:service:orders:instance:12345

Platform-independent identifier using URN scheme. Good for internal services.

Custom Schemes

myapp://services/orders/v2

Custom URI schemes specific to your application ecosystem.

Path-Based

/services/orders/v1/instance-abc123

Simple path notation for internal systems and services.

Source Metadata

Beyond just the source identifier, it's helpful to include additional metadata about the source:

{
  "source": "https://api.example.com/orders",
  "sourceMetadata": {
    "serviceName": "order-service",
    "version": "2.1.0",
    "instanceId": "order-service-pod-abc123",
    "region": "us-east-1",
    "environment": "production",
    "host": "ip-10-0-1-23.ec2.internal"
  }
}

This additional context helps with debugging, distributed tracing, and understanding system behavior.

Source Best Practices
  • •
    Be consistent: Use a standard format across all your services
  • •
    Be specific: Include enough detail to trace back to the exact producer
  • •
    Version your sources: Include API or service version in the source identifier
  • •
    Make them resolvable: When using URLs, they should ideally resolve to documentation
  • •
    Include instance information: For distributed systems, identify the specific instance
  • •
    Don't use temporary identifiers: Sources should be stable and meaningful
Source vs Subject

It's important to distinguish between the source and the subjectof an event:

Source

WHERE the event came from. The service, application, or component that produced the event.

/services/order-service

Subject

WHAT the event is about. The entity or aggregate that the event describes.

order-12345

Example: Complete Event with Source
{
  "eventId": "evt-550e8400",
  "eventType": "OrderPlaced",
  "source": "https://api.example.com/orders/v1",
  "subject": "order-12345",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "customerId": "customer-789",
    "totalAmount": 59.98
  },
  "metadata": {
    "sourceVersion": "2.1.0",
    "sourceInstance": "order-service-pod-abc123"
  }
}