From e60550f437986d710c7f4bd3dc069a8c9e8637c1 Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Thu, 23 Sep 2021 14:25:36 +0200 Subject: [PATCH 1/5] update spec + add app/internal --- specs/agents/tracing-spans.md | 11 +++++++++++ tests/agents/json-specs/span_types.json | 17 +++++++++++------ 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/specs/agents/tracing-spans.md b/specs/agents/tracing-spans.md index e5525753..85a863ec 100644 --- a/specs/agents/tracing-spans.md +++ b/specs/agents/tracing-spans.md @@ -12,6 +12,17 @@ Spans will also have a `transaction_id`, which is the `id` of the current transaction. While not necessary for distributed tracing, this inclusion allows for simpler and more performant UI queries. +### Transaction and Span type and subtype fields + +Each transaction has a `type` field, each span has both `type` and `subtype` fields. +The values for each of those fields is protocol-specific and defined in the respective instrumenation specification +for each protocol. + +For spans, they must fit the [span type specification in JSON format](../../tests/agents/json-specs/span_types.json). +In order to help align all agents on this specification, changing `type` and `subtype` field values is not considered +to be a _breaking change_, but rather a _potentially breaking change_ if for example existing users rely on values to +build visualizations. + ### Span outcome The `outcome` property denotes whether the span represents a success or failure, it is used to compute error rates diff --git a/tests/agents/json-specs/span_types.json b/tests/agents/json-specs/span_types.json index 18189088..ed1847cf 100644 --- a/tests/agents/json-specs/span_types.json +++ b/tests/agents/json-specs/span_types.json @@ -20,32 +20,37 @@ "java" ] }, + "internal": { + "__description": "Application generic internal span for controller/handler/processing delegation", + "__used_by": [ + ] + }, "controller": { - "__description": "Application controller actions", + "__description": "Deprecated: use app/internal instead", "__used_by": [ "ruby" ] }, "graphql": { - "__description": "Incoming GraphQL requests", + "__description": "Deprecated: use app/internal instead", "__used_by": [ "ruby" ] }, "mailer": { - "__description": "Application mailer actions", + "__description": "Deprecated: use app/internal instead", "__used_by": [ "ruby" ] }, "resource": { - "__description": "Application resource actions", + "__description": "Deprecated: use app/internal instead", "__used_by": [ "ruby" ] }, "handler": { - "__description": "Application handler", + "__description": "Deprecated: use app/internal instead", "__used_by": [ "java" ] @@ -223,7 +228,7 @@ } }, "json": { - "__description": "JSON parsing and generation", + "__description": "Deprecated: use app/internal instead", "subtypes": { "parse": { "__description": "JSON parsing" From 9718e5352cd9bbc3c8827f031bc72aabf189a475 Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Thu, 23 Sep 2021 14:39:34 +0200 Subject: [PATCH 2/5] deprecate few values --- tests/agents/json-specs/span_types.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tests/agents/json-specs/span_types.json b/tests/agents/json-specs/span_types.json index ed1847cf..dce27ceb 100644 --- a/tests/agents/json-specs/span_types.json +++ b/tests/agents/json-specs/span_types.json @@ -146,7 +146,8 @@ "mssql": { "__description": "Microsoft SQL Server", "__used_by": [ - "nodejs" + "nodejs", + "java" ] }, "mysql": { @@ -182,13 +183,13 @@ ] }, "sqlite3": { - "__description": "SQLite 3", + "__description": "Deprecated: use db/sqlite", "__used_by": [ "ruby" ] }, "sqlserver": { - "__description": "Microsoft SQL Server", + "__description": "Deprecated: use db/mssql", "__used_by": [ "java" ] From ef2f38e3e0aa8a1a38a0697d6b42ad6dd787c251 Mon Sep 17 00:00:00 2001 From: SylvainJuge Date: Thu, 23 Sep 2021 17:56:39 +0200 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Colton Myers --- specs/agents/tracing-spans.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/agents/tracing-spans.md b/specs/agents/tracing-spans.md index 85a863ec..70f860df 100644 --- a/specs/agents/tracing-spans.md +++ b/specs/agents/tracing-spans.md @@ -15,10 +15,10 @@ for simpler and more performant UI queries. ### Transaction and Span type and subtype fields Each transaction has a `type` field, each span has both `type` and `subtype` fields. -The values for each of those fields is protocol-specific and defined in the respective instrumenation specification +The values for each of those fields is protocol-specific and defined in the respective instrumentation specification for each protocol. -For spans, they must fit the [span type specification in JSON format](../../tests/agents/json-specs/span_types.json). +For spans, the type/subtype must fit the [span type specification in JSON format](../../tests/agents/json-specs/span_types.json). In order to help align all agents on this specification, changing `type` and `subtype` field values is not considered to be a _breaking change_, but rather a _potentially breaking change_ if for example existing users rely on values to build visualizations. From 51587d535f5f3629a3c7ea499540e71036492805 Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Thu, 2 Dec 2021 09:17:55 +0100 Subject: [PATCH 4/5] use 'type.subtype' notation for deprecated values --- tests/agents/json-specs/span_types.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/agents/json-specs/span_types.json b/tests/agents/json-specs/span_types.json index dce27ceb..193489a7 100644 --- a/tests/agents/json-specs/span_types.json +++ b/tests/agents/json-specs/span_types.json @@ -26,31 +26,31 @@ ] }, "controller": { - "__description": "Deprecated: use app/internal instead", + "__description": "Deprecated: use app.internal instead", "__used_by": [ "ruby" ] }, "graphql": { - "__description": "Deprecated: use app/internal instead", + "__description": "Deprecated: use app.internal instead", "__used_by": [ "ruby" ] }, "mailer": { - "__description": "Deprecated: use app/internal instead", + "__description": "Deprecated: use app.internal instead", "__used_by": [ "ruby" ] }, "resource": { - "__description": "Deprecated: use app/internal instead", + "__description": "Deprecated: use app.internal instead", "__used_by": [ "ruby" ] }, "handler": { - "__description": "Deprecated: use app/internal instead", + "__description": "Deprecated: use app.internal instead", "__used_by": [ "java" ] @@ -229,7 +229,7 @@ } }, "json": { - "__description": "Deprecated: use app/internal instead", + "__description": "Deprecated: use app.internal instead", "subtypes": { "parse": { "__description": "JSON parsing" From 01d9b5539b8c5c1caf327fcd2982d7721f95cba3 Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Thu, 2 Dec 2021 09:23:09 +0100 Subject: [PATCH 5/5] clarify wording for potentially breaking changes --- specs/agents/tracing-spans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/agents/tracing-spans.md b/specs/agents/tracing-spans.md index 70f860df..54f6af92 100644 --- a/specs/agents/tracing-spans.md +++ b/specs/agents/tracing-spans.md @@ -21,7 +21,7 @@ for each protocol. For spans, the type/subtype must fit the [span type specification in JSON format](../../tests/agents/json-specs/span_types.json). In order to help align all agents on this specification, changing `type` and `subtype` field values is not considered to be a _breaking change_, but rather a _potentially breaking change_ if for example existing users rely on values to -build visualizations. +build visualizations. As a consequence, modification of those values is not limited to major versions. ### Span outcome