span type/subtype: alignment step 1 (#513)

* update spec + add app/internal

* deprecate few values

* Apply suggestions from code review

Co-authored-by: Colton Myers <colton.myers@gmail.com>

* use 'type.subtype' notation for deprecated values

* clarify wording for potentially breaking changes

Co-authored-by: Colton Myers <colton.myers@gmail.com>

Author: SylvainJuge

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 instrumentation specification
+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. As a consequence, modification of those values is not limited to major versions.
+
 ### Span outcome
 
 The `outcome` property denotes whether the span represents a success or failure, it is used to compute error rates

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"
         ]
@@ -141,7 +146,8 @@
       "mssql": {
         "__description": "Microsoft SQL Server",
         "__used_by": [
-          "nodejs"
+          "nodejs",
+          "java"
         ]
       },
       "mysql": {
@@ -177,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"
         ]
@@ -223,7 +229,7 @@
     }
   },
   "json": {
-    "__description": "JSON parsing and generation",
+    "__description": "Deprecated: use app.internal instead",
     "subtypes": {
       "parse": {
         "__description": "JSON parsing"