deprecate specified format of Span#toString() and Transaction#toStrin…

…g() (#2349)

Refs: #2348

CHANGELOG.asciidoc

@@ -40,10 +40,14 @@ Notes:
 [float]
 ===== Bug fixes
 
+* <<span-to-string,`span.toString()`>> and <<transaction-to-string,`transaction.toString()`>>
+  have been *deprecated*. The exact string output may change in v4 of the
+  agent.
+
 * Add `Span.ids` and `Transaction.ids` to TypeScript types. ({pull}2347[#2347])
 
-* Improve `span.sync` determination (fixes {issue}1996[#1996]) and stop
-  reporting `transaction.sync` which was never used ({issue}2292[#2292]).
+* Improve `span.sync` determination (fixes {issues}1996[#1996]) and stop
+  reporting `transaction.sync` which was never used ({issues}2292[#2292]).
   A minor semantic change is that `span.sync` is not set to a final value
   until `span.end()` is called. Before `span.end()` the value will always
   by `true`.

docs/agent-api.asciidoc

@@ -822,7 +822,7 @@ apm.clearPatches(['timers'])
 
 `apm.currentTraceIds` produces an object containing `trace.id` and either `transaction.id` or `span.id` when a current transaction or span is available.
 When no transaction or span is available it will return an empty object.
-This enables log correlation to APM traces with structured loggers.
+This enables <<log-correlation,log correlation>> to APM traces with structured loggers.
 
 [source,js]
 ----
@@ -837,17 +837,6 @@ This enables log correlation to APM traces with structured loggers.
 }
 ----
 
-All current trace id objects,
-including the empty form,
-include a `toString()` implementation.
-This enables log correlation to APM traces with text-only loggers.
-
-[source,js]
-----
-"trace.id=abc123 transaction.id=abc123"
-// or ...
-"trace.id=abc123 span.id=abc123"
-----
 // end::currentTraceIds[]
 
 [[apm-register-custom-metrics]]

docs/span-api.asciidoc

@@ -147,10 +147,12 @@ This enables log correlation to APM traces with structured loggers.
 }
 ----
 
+
 [[span-to-string]]
-==== `span.toString()`
+==== `span.toString()` deprecated:[v3.23.0]
 
-[small]#Added in: v2.17.0#
+[small]#Added in: v2.17.0# +
+[small]#Deprecated in: v3.23.0#
 
 Produces a string representation of the span to inject in log messages.
 This enables log correlation to APM traces with text-only loggers.
@@ -160,6 +162,18 @@ This enables log correlation to APM traces with text-only loggers.
 "trace.id=abc123 span.id=abc123"
 ----
 
+Relying on the format of `span.toString()` has been **deprecated** and may
+change in v4 of the agent. Prefer the use of <<span-ids,`span.ids`>> or
+<<apm-current-trace-ids,`apm.currentTraceIds`>>. The v3 format may be reproduced
+via:
+
+[source,js]
+----
+const { stringify } = require('querystring')
+console.log( stringify(span.ids, ' ', '=')) )
+----
+
+
 [[span-end]]
 ==== `span.end([endTime])`
 

docs/transaction-api.asciidoc

@@ -210,10 +210,12 @@ This enables log correlation to APM traces with structured loggers.
 }
 ----
 
+
 [[transaction-to-string]]
-==== `transaction.toString()`
+==== `transaction.toString()` deprecated:[v3.23.0]
 
-[small]#Added in: v2.17.0#
+[small]#Added in: v2.17.0# +
+[small]#Deprecated in: v3.23.0#
 
 Produces a string representation of the transaction to inject in log messages.
 This enables log correlation to APM traces with text-only loggers.
@@ -223,6 +225,18 @@ This enables log correlation to APM traces with text-only loggers.
 "trace.id=abc123 transaction.id=abc123"
 ----
 
+Relying on the format of `transaction.toString()` has been **deprecated** and may
+change in v4 of the agent. Prefer the use of <<transaction-ids,`transaction.ids`>> or
+<<apm-current-trace-ids,`apm.currentTraceIds`>>. The v3 format may be reproduced
+via:
+
+[source,js]
+----
+const { stringify } = require('querystring')
+console.log( stringify(transaction.ids, ' ', '=')) )
+----
+
+
 [[transaction-end]]
 ==== `transaction.end([result][, endTime])`