Reference: Protobuf Schema

Package

syntax = "proto3";
package aires.v1;

All messages are in the aires.v1 package.

Event

The atomic unit of data in Aires. Every observability signal — logs, traces, metrics, HTTP events, errors, AI agent activity — is represented as an Event.

message Event {
  string id = 1;
  fixed64 timestamp_ns = 2;
  fixed64 observed_timestamp_ns = 3;
  string service = 4;
  string environment = 5;
  string host = 6;
  string instance = 7;
  Severity severity = 8;
  string message = 9;
  string display_text = 10;
  bytes body = 11;
  string trace_id = 12;
  string span_id = 13;
  string parent_span_id = 14;
  string subtrace_id = 15;
  string session_id = 16;
  string user_id = 17;
  string agent_id = 18;
  string source_file = 19;
  int32 source_line = 20;
  string source_function = 21;
  string category = 22;
  string kind = 23;
  repeated string tags = 24;
  map<string, string> attributes = 25;
  map<string, bytes> data = 26;
  repeated RelatedObject related = 27;
  MetricValue metric = 28;
  HttpInfo http = 29;
  ErrorInfo error = 30;
  ResourceInfo resource = 31;
}

Fields

#	Field	Type	Description
1	id	string	Unique event ID. Generated by the SDK as a UUID v7 (time-ordered).
2	timestamp_ns	fixed64	Nanosecond-precision Unix timestamp. Set by the SDK at event creation time. Uses fixed64 for efficient encoding of large values.
3	observed_timestamp_ns	fixed64	Timestamp when the collector received the event. Set by the collector, not the SDK.
4	service	string	Service name (e.g. "workforce-api"). Set from SDK config.
5	environment	string	Environment name (e.g. "production"). Set from SDK config.
6	host	string	Hostname or pod name.
7	instance	string	Instance/replica identifier for distinguishing multiple instances of the same service.
8	severity	Severity	Log severity level (enum).
9	message	string	Human-readable log message. Should be plain text, searchable.
10	display_text	string	Formatted display text. May include ANSI escape codes or rich formatting.
11	body	bytes	Raw binary body. For payloads that don’t fit in message (binary data, large JSON, etc.).
12	trace_id	string	Distributed trace ID. W3C Trace Context compatible. Shared across all events in a distributed operation.
13	span_id	string	Span identifier within a trace. Unique per unit of work.
14	parent_span_id	string	Parent span ID. Links a span to its parent, forming a tree.
15	subtrace_id	string	Sub-trace ID for grouping events within a nested operation (e.g. an AI agent’s task within a larger request).
16	session_id	string	Session identifier. Groups events across multiple requests from the same user/agent session.
17	user_id	string	Authenticated user identifier.
18	agent_id	string	AI agent identifier. For tracking agent behavior in AI systems.
19	source_file	string	Source file path where the event originated.
20	source_line	int32	Line number in the source file.
21	source_function	string	Function or method name.
22	category	string	Event category for grouping: "http", "db", "auth", "ai", "k8s", etc.
23	kind	string	Event kind: "log", "span", "metric", "request", "response", "error".
24	tags	repeated string	Free-form string tags for filtering and categorization.
25	attributes	map<string, string>	Structured string key-value pairs. For data you want to filter and search on.
26	data	map<string, bytes>	Arbitrary data blobs. Values are JSON-serialized bytes. For complex objects that don’t fit in string attributes.
27	related	repeated RelatedObject	Links to related entities (tasks, agents, workspaces, etc.).
28	metric	MetricValue	Metric data (when kind = "metric").
29	http	HttpInfo	HTTP request/response info (when category = "http").
30	error	ErrorInfo	Error details (when logging errors).
31	resource	ResourceInfo	Resource context. Set by the collector, not the SDK. Contains Kubernetes metadata.

Severity

enum Severity {
  SEVERITY_UNSPECIFIED = 0;
  TRACE = 1;
  DEBUG = 2;
  INFO = 3;
  WARN = 4;
  ERROR = 5;
  FATAL = 6;
}

Value	Name	Description
0	SEVERITY_UNSPECIFIED	Default/unknown severity.
1	TRACE	Finest-grained debug information.
2	DEBUG	Development diagnostics.
3	INFO	Normal operational events.
4	WARN	Potential problems that may need attention.
5	ERROR	Errors that need investigation.
6	FATAL	Unrecoverable errors; system cannot continue.

RelatedObject

Links an event to a related entity for navigation and correlation.

message RelatedObject {
  string type = 1;
  string id = 2;
  string label = 3;
  string url = 4;
}

#	Field	Type	Description
1	type	string	Entity type: "task", "agent", "workspace", "request", "user", etc.
2	id	string	Entity identifier.
3	label	string	Human-readable label for display.
4	url	string	Optional deep-link URL for navigation.

MetricValue

Metric data attached to events with kind = "metric".

message MetricValue {
  string name = 1;
  double value = 2;
  string unit = 3;
  MetricType type = 4;
}

#	Field	Type	Description
1	name	string	Metric name (e.g. "http.request.duration").
2	value	double	Numeric value.
3	unit	string	Unit of measurement: "ms", "bytes", "count", "percent", etc.
4	type	MetricType	Metric type enum.

MetricType

enum MetricType {
  METRIC_UNSPECIFIED = 0;
  GAUGE = 1;
  COUNTER = 2;
  HISTOGRAM = 3;
  SUMMARY = 4;
}

Value	Name	Description
0	METRIC_UNSPECIFIED	Default/unknown type.
1	GAUGE	Point-in-time value (can go up or down).
2	COUNTER	Cumulative value (only increases).
3	HISTOGRAM	Individual observation for bucketed distribution.
4	SUMMARY	Pre-computed quantile summary.

HttpInfo

HTTP request/response details for events with category = "http".

message HttpInfo {
  string method = 1;
  string url = 2;
  string path = 3;
  int32 status_code = 4;
  int64 request_size = 5;
  int64 response_size = 6;
  int64 duration_ms = 7;
  string user_agent = 8;
  string remote_addr = 9;
}

#	Field	Type	Description
1	method	string	HTTP method: "GET", "POST", "PUT", "DELETE", etc.
2	url	string	Full request URL.
3	path	string	URL path without query string (e.g. "/api/tasks").
4	status_code	int32	HTTP response status code (e.g. 200, 404, 500).
5	request_size	int64	Request body size in bytes.
6	response_size	int64	Response body size in bytes.
7	duration_ms	int64	Request duration in milliseconds.
8	user_agent	string	User-Agent header value.
9	remote_addr	string	Client IP address.

ErrorInfo

Error details for error events.

message ErrorInfo {
  string type = 1;
  string message = 2;
  string stack = 3;
  bool handled = 4;
}

#	Field	Type	Description
1	type	string	Error class/type name (e.g. "DatabaseError", "ValidationError").
2	message	string	Error message text.
3	stack	string	Stack trace.
4	handled	bool	true if the error was caught and handled; false if it was an unhandled exception.

ResourceInfo

Resource context injected by the collector. Contains infrastructure/deployment metadata.

message ResourceInfo {
  string cluster = 1;
  string namespace = 2;
  string pod = 3;
  string container = 4;
  string node = 5;
  map<string, string> labels = 6;
}

#	Field	Type	Description
1	cluster	string	Kubernetes cluster name.
2	namespace	string	Kubernetes namespace.
3	pod	string	Pod name.
4	container	string	Container name within the pod.
5	node	string	Kubernetes node name.
6	labels	map<string, string>	Kubernetes labels from the pod/deployment.

EventBatch

Events are shipped in batches for transport efficiency.

message EventBatch {
  repeated Event events = 1;
  string sdk_name = 2;
  string sdk_version = 3;
  string sdk_language = 4;
}

#	Field	Type	Description
1	events	repeated Event	The batch of events.
2	sdk_name	string	SDK identifier (e.g. "aires-sdk-rust", "aires-sdk-ts", "aires-sdk-python").
3	sdk_version	string	SDK version string (e.g. "0.1.0").
4	sdk_language	string	SDK language: "rust", "typescript", "python".

AiresCollector Service

The gRPC service definition.

service AiresCollector {
  rpc Ingest(EventBatch) returns (IngestResponse);
  rpc IngestStream(stream EventBatch) returns (IngestResponse);
}

RPC	Input	Output	Description
Ingest	EventBatch	IngestResponse	Ship a single batch of events. Used for short-lived processes or periodic flushes.
IngestStream	stream EventBatch	IngestResponse	Stream batches continuously over a persistent connection. Used for long-lived processes. Returns a single response when the stream ends.

IngestResponse

message IngestResponse {
  int64 accepted = 1;
  int64 rejected = 2;
  repeated string errors = 3;
}

#	Field	Type	Description
1	accepted	int64	Number of events successfully accepted.
2	rejected	int64	Number of events rejected (validation failures).
3	errors	repeated string	Error messages for rejected events.