From d1a640c94d8e7ac6699ac33dc5239f298b8eac75 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Tue, 5 Nov 2024 14:18:43 -0500 Subject: [PATCH 01/21] Adding trace profile with trace objects and dependencies. --- dictionary.json | 17 +++++++++++- events/application/api_activity.json | 10 +++++-- events/network/http_activity.json | 10 +++++-- objects/span.json | 41 ++++++++++++++++++++++++++++ objects/trace.json | 36 ++++++++++++++++++++++++ profiles/trace.json | 15 ++++++++++ 6 files changed, 124 insertions(+), 5 deletions(-) create mode 100644 objects/span.json create mode 100644 objects/trace.json create mode 100644 profiles/trace.json diff --git a/dictionary.json b/dictionary.json index 1a9476673..4a20fb0c2 100644 --- a/dictionary.json +++ b/dictionary.json @@ -3315,6 +3315,11 @@ "description": "The parent process of this process object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", "type": "process" }, + "parent_span": { + "caption": "Parent Span", + "description": "The parent span of this span object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", + "type": "span" + }, "parent_uid": { "caption": "Parent Unique ID", "description": "The unique identifier of an object's parent object. See specific usage.", @@ -4342,6 +4347,11 @@ "description": " The Server Name Indication (SNI) extension sent by the client.", "type": "string_t" }, + "span": { + "caption": "Span", + "description": "The information about the span. See specific usage.", + "type": "span" + }, "sp_name": { "caption": "OS Service Pack", "description": "The name of the latest Service Pack.", @@ -4744,6 +4754,11 @@ "description": "The event transmission time from one device to another. See specific usage.", "type": "timestamp_t" }, + "trace": { + "caption": "Trace", + "description": "The information about the trace. See specific usage.", + "type": "trace" + }, "tree_uid": { "caption": "Tree UID", "description": "The tree id is a unique SMB identifier which represents an open connection to a share.", @@ -5202,4 +5217,4 @@ } } } -} \ No newline at end of file +} diff --git a/events/application/api_activity.json b/events/application/api_activity.json index 91432f222..e9c2b9442 100644 --- a/events/application/api_activity.json +++ b/events/application/api_activity.json @@ -5,6 +5,9 @@ "extends": "application", "name": "api_activity", "attributes": { + "$include": [ + "profiles/trace.json" + ], "activity_id": { "enum": { "1": { @@ -58,5 +61,8 @@ "group": "primary", "requirement": "required" } - } -} \ No newline at end of file + }, + "profiles": [ + "trace" + ] +} diff --git a/events/network/http_activity.json b/events/network/http_activity.json index f4ac0878d..8d4f6bbdd 100644 --- a/events/network/http_activity.json +++ b/events/network/http_activity.json @@ -5,6 +5,9 @@ "extends": "network", "name": "http_activity", "attributes": { + "$include": [ + "profiles/trace.json" + ], "activity_id": { "enum": { "1": { @@ -62,5 +65,8 @@ "group": "primary", "requirement": "recommended" } - } -} \ No newline at end of file + }, + "profiles": [ + "trace" + ] +} diff --git a/objects/span.json b/objects/span.json new file mode 100644 index 000000000..f2be9f9d3 --- /dev/null +++ b/objects/span.json @@ -0,0 +1,41 @@ +{ + "caption": "Span", + "description": "The attributes associated with an event containing span data.", + "extends": "object", + "name": "span", + "attributes": { + "uid": { + "description": "The unique identifier of the span used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", + "requirement": "required" + }, + "service": { + "description": "Identifies the service or component creating the span, which helps track its path through a distributed system.", + "requirement": "optional" + }, + "operation": { + "description": "Describes an actions performed in a span, such as API requests, database queries, or computations.", + "requirement": "optional", + "is_array": true + }, + "parent_span": { + "description": "The parent span of this span object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", + "requirement": "optional" + }, + "start_time": { + "description": "The start timestamp of the span, essential for identifying latency and performance bottlenecks.", + "requirement": "optional" + }, + "end_time": { + "description": "The end timestamp of the span, essential for identifying latency and performance bottlenecks.", + "requirement": "optional" + }, + "duration": { + "description": "The span duration, the amount of time the trace covers from start_time to end_time in milliseconds.", + "requirement": "optional" + }, + "status_code": { + "description": "Indicates whether the operations in the span were successful, failed, or had an error, aiding in pinpointing issues.", + "requirement": "optional" + } + } +} diff --git a/objects/trace.json b/objects/trace.json new file mode 100644 index 000000000..30441ca6b --- /dev/null +++ b/objects/trace.json @@ -0,0 +1,36 @@ +{ + "caption": "Trace", + "description": "The trace object contains information about distruibuted traces which are critical to observability and describe how requests move through a system, capturing each step's timing and status.", + "extends": "object", + "name": "trace", + "attributes": { + "uid": { + "description": "The unique identifier of the trace used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", + "requirement": "required" + }, + "span": { + "description": "The attributes associated with a span within a distributed trace.", + "requirement": "optional" + }, + "service": { + "description": "Identifies the service or component generating the trace.", + "requirement": "optional" + }, + "status_code": { + "description": "Indicates whether the operations in the trace were successful, failed, or had an error, aiding in pinpointing issues.", + "requirement": "optional" + }, + "start_time": { + "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks.", + "requirement": "optional" + }, + "end_time": { + "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks.", + "requirement": "optional" + }, + "duration": { + "description": "The trace duration, the amount of time the trace covers from start_time to end_time in milliseconds.", + "requirement": "optional" + } + } +} diff --git a/profiles/trace.json b/profiles/trace.json new file mode 100644 index 000000000..aad8ce67d --- /dev/null +++ b/profiles/trace.json @@ -0,0 +1,15 @@ +{ + "description": "The Trace Profile extends the OCSF framework to capture and standardize observability events, specifically targeting trace-level data. This profile enables integration and normalization of distributed tracing information, allowing OCSF events to retain essential trace context such as trace IDs, span relationships, and service dependencies.", + "meta": "profile", + "caption": "Trace", + "name": "trace", + "annotations": { + "group": "primary" + }, + "attributes": { + "trace": { + "description": "The trace object contains information about distruibuted traces which are critical to observability and describe how requests move through a system, capturing each step's timing and status.", + "requirement": "recommended" + } + } +} From c6286e64e84453b723cb6361427901b9b086f38f Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 6 Nov 2024 14:53:30 -0500 Subject: [PATCH 02/21] Reverting span operation back to string in span.json Reverting span operation back to string in span.json Signed-off-by: Adam Gregory --- objects/span.json | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/objects/span.json b/objects/span.json index f2be9f9d3..76b18e830 100644 --- a/objects/span.json +++ b/objects/span.json @@ -13,9 +13,8 @@ "requirement": "optional" }, "operation": { - "description": "Describes an actions performed in a span, such as API requests, database queries, or computations.", - "requirement": "optional", - "is_array": true + "description": "Describes an action performed in a span, such as API requests, database queries, or computations.", + "requirement": "optional" }, "parent_span": { "description": "The parent span of this span object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", From 740ed9a47e4797cad80221045a81d2eb4b3c58fb Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Thu, 7 Nov 2024 10:20:17 -0500 Subject: [PATCH 03/21] Updating dictionary alphabetical ordering. Signed-off-by: Adam Gregory --- dictionary.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/dictionary.json b/dictionary.json index 4a20fb0c2..84500fefc 100644 --- a/dictionary.json +++ b/dictionary.json @@ -4347,11 +4347,6 @@ "description": " The Server Name Indication (SNI) extension sent by the client.", "type": "string_t" }, - "span": { - "caption": "Span", - "description": "The information about the span. See specific usage.", - "type": "span" - }, "sp_name": { "caption": "OS Service Pack", "description": "The name of the latest Service Pack.", @@ -4362,6 +4357,11 @@ "description": "The version number of the latest Service Pack.", "type": "integer_t" }, + "span": { + "caption": "Span", + "description": "The information about the span. See specific usage.", + "type": "span" + }, "speed": { "caption": "Speed", "description": "Ground speed of flight. This value is provided in meters per second with a minimum resolution of 0.25 m/s. Special Values: Invalid, No Value, or Unknown: 255 m/s.", From e83bbba097352ae6addab59d03948ace75534fb0 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Thu, 7 Nov 2024 10:22:32 -0500 Subject: [PATCH 04/21] Update alphabetical sorting on span.json Signed-off-by: Adam Gregory --- objects/span.json | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/objects/span.json b/objects/span.json index 76b18e830..141c398f4 100644 --- a/objects/span.json +++ b/objects/span.json @@ -4,12 +4,12 @@ "extends": "object", "name": "span", "attributes": { - "uid": { - "description": "The unique identifier of the span used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", - "requirement": "required" + "duration": { + "description": "The span duration, the amount of time the trace covers from start_time to end_time in milliseconds.", + "requirement": "optional" }, - "service": { - "description": "Identifies the service or component creating the span, which helps track its path through a distributed system.", + "end_time": { + "description": "The end timestamp of the span, essential for identifying latency and performance bottlenecks.", "requirement": "optional" }, "operation": { @@ -20,21 +20,21 @@ "description": "The parent span of this span object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", "requirement": "optional" }, - "start_time": { - "description": "The start timestamp of the span, essential for identifying latency and performance bottlenecks.", - "requirement": "optional" - }, - "end_time": { - "description": "The end timestamp of the span, essential for identifying latency and performance bottlenecks.", + "service": { + "description": "Identifies the service or component creating the span, which helps track its path through a distributed system.", "requirement": "optional" }, - "duration": { - "description": "The span duration, the amount of time the trace covers from start_time to end_time in milliseconds.", + "start_time": { + "description": "The start timestamp of the span, essential for identifying latency and performance bottlenecks.", "requirement": "optional" }, "status_code": { "description": "Indicates whether the operations in the span were successful, failed, or had an error, aiding in pinpointing issues.", "requirement": "optional" + }, + "uid": { + "description": "The unique identifier of the span used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", + "requirement": "required" } } } From 4b4de4b6ee84081ab7c6c644d90cc054b7a639fc Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Thu, 7 Nov 2024 10:27:02 -0500 Subject: [PATCH 05/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/span.json b/objects/span.json index 141c398f4..4f96a1448 100644 --- a/objects/span.json +++ b/objects/span.json @@ -5,7 +5,7 @@ "name": "span", "attributes": { "duration": { - "description": "The span duration, the amount of time the trace covers from start_time to end_time in milliseconds.", + "description": "The span duration, the amount of time the span covers from start_time to end_time in milliseconds.", "requirement": "optional" }, "end_time": { From 4b866e461cf72ea00ba816f23a5adaa8b22bc5fa Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Thu, 7 Nov 2024 10:28:52 -0500 Subject: [PATCH 06/21] Update description on parent_span Signed-off-by: Adam Gregory --- objects/span.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/span.json b/objects/span.json index 4f96a1448..2d8154edf 100644 --- a/objects/span.json +++ b/objects/span.json @@ -17,7 +17,7 @@ "requirement": "optional" }, "parent_span": { - "description": "The parent span of this span object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", + "description": "The parent span of this span object. It is recommended to only populate this field for the recent span object, to prevent deep nesting.", "requirement": "optional" }, "service": { From a86db90fa0380cf0a86068d7f41ab4eddfe01059 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Thu, 7 Nov 2024 10:57:33 -0500 Subject: [PATCH 07/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/span.json b/objects/span.json index 2d8154edf..1ae5b067c 100644 --- a/objects/span.json +++ b/objects/span.json @@ -17,7 +17,7 @@ "requirement": "optional" }, "parent_span": { - "description": "The parent span of this span object. It is recommended to only populate this field for the recent span object, to prevent deep nesting.", + "description": "The parent span of this span object. It is recommended to only populate this field for the recent parent span object, to prevent deep nesting.", "requirement": "optional" }, "service": { From 7939636ce6993755d40e8e8742941514f2f17ccb Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Tue, 12 Nov 2024 16:41:41 -0500 Subject: [PATCH 08/21] Update trace.json Signed-off-by: Adam Gregory --- objects/trace.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/trace.json b/objects/trace.json index 30441ca6b..51fe53840 100644 --- a/objects/trace.json +++ b/objects/trace.json @@ -1,6 +1,6 @@ { "caption": "Trace", - "description": "The trace object contains information about distruibuted traces which are critical to observability and describe how requests move through a system, capturing each step's timing and status.", + "description": "The trace object contains information about distributed traces which are critical to observability and describe how requests move through a system, capturing each step's timing and status.", "extends": "object", "name": "trace", "attributes": { From 7b2f0e3ba8267e085e7e9b45f26b088528d0452e Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:00:36 -0500 Subject: [PATCH 09/21] Update dictionary.json Signed-off-by: Adam Gregory --- dictionary.json | 5 ----- 1 file changed, 5 deletions(-) diff --git a/dictionary.json b/dictionary.json index 84500fefc..e289ccad7 100644 --- a/dictionary.json +++ b/dictionary.json @@ -3315,11 +3315,6 @@ "description": "The parent process of this process object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", "type": "process" }, - "parent_span": { - "caption": "Parent Span", - "description": "The parent span of this span object. It is recommended to only populate this field for the first process object, to prevent deep nesting.", - "type": "span" - }, "parent_uid": { "caption": "Parent Unique ID", "description": "The unique identifier of an object's parent object. See specific usage.", From 549a39607a1fb6c9286ee69c7094ca19ae24c414 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:00:55 -0500 Subject: [PATCH 10/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/objects/span.json b/objects/span.json index 1ae5b067c..69b134793 100644 --- a/objects/span.json +++ b/objects/span.json @@ -8,26 +8,18 @@ "description": "The span duration, the amount of time the span covers from start_time to end_time in milliseconds.", "requirement": "optional" }, - "end_time": { - "description": "The end timestamp of the span, essential for identifying latency and performance bottlenecks.", - "requirement": "optional" - }, "operation": { "description": "Describes an action performed in a span, such as API requests, database queries, or computations.", "requirement": "optional" }, - "parent_span": { - "description": "The parent span of this span object. It is recommended to only populate this field for the recent parent span object, to prevent deep nesting.", + "parent_uid": { + "description": "The parent span id of this span object.", "requirement": "optional" }, "service": { "description": "Identifies the service or component creating the span, which helps track its path through a distributed system.", "requirement": "optional" }, - "start_time": { - "description": "The start timestamp of the span, essential for identifying latency and performance bottlenecks.", - "requirement": "optional" - }, "status_code": { "description": "Indicates whether the operations in the span were successful, failed, or had an error, aiding in pinpointing issues.", "requirement": "optional" From a8439d15fb07d2f29331225ce00645fb08535f5e Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:04:29 -0500 Subject: [PATCH 11/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/objects/span.json b/objects/span.json index 69b134793..cf6504d93 100644 --- a/objects/span.json +++ b/objects/span.json @@ -27,6 +27,18 @@ "uid": { "description": "The unique identifier of the span used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", "requirement": "required" + }, + "start_time": { + "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks.", + "requirement": "optional" + }, + "end_time": { + "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks.", + "requirement": "optional" + }, + "duration": { + "description": "The trace duration, the amount of time the trace covers from start_time to end_time in milliseconds.", + "requirement": "optional" } } } From 4349fa4fea70c4f4923bfbafcb36dba60a361c91 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:18:22 -0500 Subject: [PATCH 12/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/objects/span.json b/objects/span.json index cf6504d93..715c369f3 100644 --- a/objects/span.json +++ b/objects/span.json @@ -5,7 +5,15 @@ "name": "span", "attributes": { "duration": { - "description": "The span duration, the amount of time the span covers from start_time to end_time in milliseconds.", + "description": "The total time, in seconds, that the span represents, calculated as the difference between start_time and end_time. It reflects the operation's performance and latency, independent of event timestamps, and accounts for normalized times used by observability tools to ensure consistency across distributed systems.", + "requirement": "optional" + }, + "end_time": { + "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks. Like the start time, this timestamp is normalized across the trace system to ensure consistency, even when events are recorded across distributed services with unsynchronized clocks. Normalized time allows for accurate duration calculations and helps observability tools track performance across services, regardless of the individual system time settings.", + "requirement": "required" + }, + "message": { + "description": "The message in a span (often refered to as a span event) serves as a way to record significant moments or occurrences during the span's lifecycle. This content typically manifests as log entries, annotations, or semi-structured events as a string, providing additional granularity and context about what happens at specific points during the execution of an operation.", "requirement": "optional" }, "operation": { @@ -13,32 +21,24 @@ "requirement": "optional" }, "parent_uid": { - "description": "The parent span id of this span object.", + "description": "The ID of the parent span for this span object, establishing its relationship in the trace hierarchy.", "requirement": "optional" }, "service": { - "description": "Identifies the service or component creating the span, which helps track its path through a distributed system.", + "description": "Identifies the service or component that generates the span, helping trace its path through the distributed system.", "requirement": "optional" }, + "start_time": { + "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks. This timestamp is normalized across the trace system, ensuring consistency even when events occur across distributed services with potentially unsynchronized clocks. By using normalized time, observability tools can provide accurate, uniform measurements of operation performance and latency, regardless of where or when the events actually occur.", + "requirement": "required" + }, "status_code": { - "description": "Indicates whether the operations in the span were successful, failed, or had an error, aiding in pinpointing issues.", + "description": "Indicates the outcome of the operation in the span, such as success, failure, or error. Issues in a span typically refer to problems such as failed operations, timeouts, service unavailability, or errors in processing that can negatively impact the performance or reliability of the system. Tracking the `status_code` helps pinpoint these issues, enabling quicker identification and resolution of system inefficiencies or faults.", "requirement": "optional" }, "uid": { - "description": "The unique identifier of the span used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", + "description": "The unique identifier for the span, used in distributed systems and microservices architectures to track and correlate requests across different components of an application. It enables tracing the flow of a request through various services.", "requirement": "required" - }, - "start_time": { - "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks.", - "requirement": "optional" - }, - "end_time": { - "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks.", - "requirement": "optional" - }, - "duration": { - "description": "The trace duration, the amount of time the trace covers from start_time to end_time in milliseconds.", - "requirement": "optional" } } } From 30e17408af57e1952d23b988eaad14bb3566f459 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:25:44 -0500 Subject: [PATCH 13/21] Update trace.json Signed-off-by: Adam Gregory --- objects/trace.json | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/objects/trace.json b/objects/trace.json index 51fe53840..82a7e1eab 100644 --- a/objects/trace.json +++ b/objects/trace.json @@ -1,36 +1,36 @@ { "caption": "Trace", - "description": "The trace object contains information about distributed traces which are critical to observability and describe how requests move through a system, capturing each step's timing and status.", + "description": "The trace object contains information about a distributed trace, which is crucial for observability. It tracks the journey of a request as it moves through various services in a system, capturing key details like timing, status, and dependencies at each step. Traces provide insights into system performance, helping to identify latency, bottlenecks, and issues in complex, distributed environments.", "extends": "object", "name": "trace", "attributes": { - "uid": { - "description": "The unique identifier of the trace used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", - "requirement": "required" - }, - "span": { - "description": "The attributes associated with a span within a distributed trace.", + "duration": { + "description": The total time, in seconds, that the trace covers, calculated as the difference between start_time and end_time. This duration helps assess the overall performance of a request as it travels across various services, and is essential for identifying latency and potential bottlenecks within the distributed system. The trace duration may differ from individual span durations due to the propagation and processing times of the trace as it spans multiple components., "requirement": "optional" }, - "service": { - "description": "Identifies the service or component generating the trace.", + "end_time": { + "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks. Like the start time, this timestamp is normalized across the trace system to ensure consistency, even when events are recorded across distributed services with unsynchronized clocks. Normalized time allows for accurate trace duration calculations and helps observability tools track overall performance across services, regardless of the individual system time settings.", "requirement": "optional" }, - "status_code": { - "description": "Indicates whether the operations in the trace were successful, failed, or had an error, aiding in pinpointing issues.", + "flags": { + "description": "A set of flags associated with the trace, used to indicate specific properties or behaviors, such as whether the trace is sampled or if it has special handling. Flags help control how traces are processed, logged, and analyzed, providing valuable context for tracing and observability tools in identifying trace characteristics or specific tracking requirements.", "requirement": "optional" }, - "start_time": { - "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks.", + "service": { + "description": "Identifies the service or component generating the trace, helping to track and correlate the flow of requests through various parts of a distributed system. This information is essential for understanding the role and performance of specific services within the broader context of system operations and for diagnosing issues across different components.", "requirement": "optional" }, - "end_time": { - "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks.", + "span": { + "description": "Represents a single unit of work or operation within a distributed trace. A span typically tracks the execution of a request across a service, capturing important details such as the operation, timestamps, and status. Spans help break down the overall trace into smaller, manageable parts, enabling detailed analysis of the performance and behavior of specific operations within the system. They are crucial for understanding latency, dependencies, and bottlenecks in complex distributed systems.", "requirement": "optional" }, - "duration": { - "description": "The trace duration, the amount of time the trace covers from start_time to end_time in milliseconds.", + "start_time": { + "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks. Like the end time, this timestamp is normalized across the trace system to ensure consistency, even when events are recorded across distributed services with unsynchronized clocks. Normalized time enables accurate trace duration calculations and helps observability tools track performance across services, regardless of the individual system time settings.", "requirement": "optional" + }, + "uid": { + "description": "The unique identifier of the trace used in distributed systems and microservices architecture to track and correlate requests across various components of an application.", + "requirement": "required" } } } From 32d0236d52a63a863ba012cdf006d153b37b2110 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:26:02 -0500 Subject: [PATCH 14/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/span.json b/objects/span.json index 715c369f3..c04f81748 100644 --- a/objects/span.json +++ b/objects/span.json @@ -1,6 +1,6 @@ { "caption": "Span", - "description": "The attributes associated with an event containing span data.", + "description": "Represents a single unit of work or operation within a distributed trace. A span typically tracks the execution of a request across a service, capturing important details such as the operation, timestamps, and status. Spans help break down the overall trace into smaller, manageable parts, enabling detailed analysis of the performance and behavior of specific operations within the system. They are crucial for understanding latency, dependencies, and bottlenecks in complex distributed systems.", "extends": "object", "name": "span", "attributes": { From 23afb61c16dbcec3f7239a6b4a7b04aacfd3c30d Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:26:38 -0500 Subject: [PATCH 15/21] Update trace.json Signed-off-by: Adam Gregory --- objects/trace.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/trace.json b/objects/trace.json index 82a7e1eab..cdc550b51 100644 --- a/objects/trace.json +++ b/objects/trace.json @@ -5,7 +5,7 @@ "name": "trace", "attributes": { "duration": { - "description": The total time, in seconds, that the trace covers, calculated as the difference between start_time and end_time. This duration helps assess the overall performance of a request as it travels across various services, and is essential for identifying latency and potential bottlenecks within the distributed system. The trace duration may differ from individual span durations due to the propagation and processing times of the trace as it spans multiple components., + "description": "The total time, in seconds, that the trace covers, calculated as the difference between start_time and end_time. This duration helps assess the overall performance of a request as it travels across various services, and is essential for identifying latency and potential bottlenecks within the distributed system. The trace duration may differ from individual span durations due to the propagation and processing times of the trace as it spans multiple components.", "requirement": "optional" }, "end_time": { From 54b0a141b524afab9c8b76362e7948c8125369b9 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Wed, 20 Nov 2024 11:27:43 -0500 Subject: [PATCH 16/21] Update trace.json Signed-off-by: Adam Gregory --- objects/trace.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/objects/trace.json b/objects/trace.json index cdc550b51..58794ede2 100644 --- a/objects/trace.json +++ b/objects/trace.json @@ -13,8 +13,9 @@ "requirement": "optional" }, "flags": { - "description": "A set of flags associated with the trace, used to indicate specific properties or behaviors, such as whether the trace is sampled or if it has special handling. Flags help control how traces are processed, logged, and analyzed, providing valuable context for tracing and observability tools in identifying trace characteristics or specific tracking requirements.", - "requirement": "optional" + "description": "The flags associated with the trace, used to indicate specific properties or behaviors, such as whether the trace is sampled or if it has special handling. Flags help control how traces are processed, logged, and analyzed, providing valuable context for tracing and observability tools in identifying trace characteristics or specific tracking requirements.", + "requirement": "optional", + "is_array" : true }, "service": { "description": "Identifies the service or component generating the trace, helping to track and correlate the flow of requests through various parts of a distributed system. This information is essential for understanding the role and performance of specific services within the broader context of system operations and for diagnosing issues across different components.", From 5bd451a780ff56f261daab21adb4ae533ffe294e Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Mon, 25 Nov 2024 11:15:23 -0500 Subject: [PATCH 17/21] Update trace.json Signed-off-by: Adam Gregory --- objects/trace.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/objects/trace.json b/objects/trace.json index 58794ede2..856197aab 100644 --- a/objects/trace.json +++ b/objects/trace.json @@ -14,8 +14,7 @@ }, "flags": { "description": "The flags associated with the trace, used to indicate specific properties or behaviors, such as whether the trace is sampled or if it has special handling. Flags help control how traces are processed, logged, and analyzed, providing valuable context for tracing and observability tools in identifying trace characteristics or specific tracking requirements.", - "requirement": "optional", - "is_array" : true + "requirement": "optional" }, "service": { "description": "Identifies the service or component generating the trace, helping to track and correlate the flow of requests through various parts of a distributed system. This information is essential for understanding the role and performance of specific services within the broader context of system operations and for diagnosing issues across different components.", From 2f9aa82ddfece39f27e53245201e990ef91cf4b0 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Mon, 25 Nov 2024 11:17:04 -0500 Subject: [PATCH 18/21] Update trace.json description Signed-off-by: Adam Gregory --- objects/trace.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/trace.json b/objects/trace.json index 856197aab..667456b26 100644 --- a/objects/trace.json +++ b/objects/trace.json @@ -1,6 +1,6 @@ { "caption": "Trace", - "description": "The trace object contains information about a distributed trace, which is crucial for observability. It tracks the journey of a request as it moves through various services in a system, capturing key details like timing, status, and dependencies at each step. Traces provide insights into system performance, helping to identify latency, bottlenecks, and issues in complex, distributed environments.", + "description": "The trace object contains information about a distributed trace, which is crucial for observability. Traces are made up of one or more spans, which are individual units of work in application activity. Traces track the journey of a request as it moves through various services in a system, capturing key details like timing, status, and dependencies at each step. Traces provide insights into system performance, helping to identify latency, bottlenecks, and issues in complex, distributed environments.", "extends": "object", "name": "trace", "attributes": { From 97334c739ac83d18c3caeec8dd190725638cf7bc Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Mon, 25 Nov 2024 11:18:33 -0500 Subject: [PATCH 19/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/objects/span.json b/objects/span.json index c04f81748..80e480d70 100644 --- a/objects/span.json +++ b/objects/span.json @@ -9,7 +9,7 @@ "requirement": "optional" }, "end_time": { - "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks. Like the start time, this timestamp is normalized across the trace system to ensure consistency, even when events are recorded across distributed services with unsynchronized clocks. Normalized time allows for accurate duration calculations and helps observability tools track performance across services, regardless of the individual system time settings.", + "description": "The end timestamp of the span, essential for identifying latency and performance bottlenecks. Like the start time, this timestamp is normalized across the observability system to ensure consistency, even when events are recorded across distributed services with unsynchronized clocks. Normalized time allows for accurate duration calculations and helps observability tools track performance across services, regardless of the individual system time settings.", "requirement": "required" }, "message": { @@ -29,7 +29,7 @@ "requirement": "optional" }, "start_time": { - "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks. This timestamp is normalized across the trace system, ensuring consistency even when events occur across distributed services with potentially unsynchronized clocks. By using normalized time, observability tools can provide accurate, uniform measurements of operation performance and latency, regardless of where or when the events actually occur.", + "description": "The start timestamp of the span, essential for identifying latency and performance bottlenecks. This timestamp is normalized across the observability system, ensuring consistency even when events occur across distributed services with potentially unsynchronized clocks. By using normalized time, observability tools can provide accurate, uniform measurements of operation performance and latency, regardless of where or when the events actually occur.", "requirement": "required" }, "status_code": { From 67d324f52b2a9cc2efdfbd757a83961e1bef3374 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Tue, 26 Nov 2024 15:17:41 -0500 Subject: [PATCH 20/21] Update trace.json Signed-off-by: Adam Gregory --- objects/trace.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/trace.json b/objects/trace.json index 667456b26..24b3b0fd1 100644 --- a/objects/trace.json +++ b/objects/trace.json @@ -5,7 +5,7 @@ "name": "trace", "attributes": { "duration": { - "description": "The total time, in seconds, that the trace covers, calculated as the difference between start_time and end_time. This duration helps assess the overall performance of a request as it travels across various services, and is essential for identifying latency and potential bottlenecks within the distributed system. The trace duration may differ from individual span durations due to the propagation and processing times of the trace as it spans multiple components.", + "description": "The total time, in milliseconds, that the trace covers, calculated as the difference between start_time and end_time. This duration helps assess the overall performance of a request as it travels across various services, and is essential for identifying latency and potential bottlenecks within the distributed system. The trace duration may differ from individual span durations due to the propagation and processing times of the trace as it spans multiple components.", "requirement": "optional" }, "end_time": { From 81966a6ae7adc36804ed8c95cae3edf0d7626b67 Mon Sep 17 00:00:00 2001 From: Adam Gregory Date: Tue, 26 Nov 2024 15:17:52 -0500 Subject: [PATCH 21/21] Update span.json Signed-off-by: Adam Gregory --- objects/span.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/span.json b/objects/span.json index 80e480d70..0ae6fb086 100644 --- a/objects/span.json +++ b/objects/span.json @@ -5,7 +5,7 @@ "name": "span", "attributes": { "duration": { - "description": "The total time, in seconds, that the span represents, calculated as the difference between start_time and end_time. It reflects the operation's performance and latency, independent of event timestamps, and accounts for normalized times used by observability tools to ensure consistency across distributed systems.", + "description": "The total time, in milliseconds, that the span represents, calculated as the difference between start_time and end_time. It reflects the operation's performance and latency, independent of event timestamps, and accounts for normalized times used by observability tools to ensure consistency across distributed systems.", "requirement": "optional" }, "end_time": {