[DOCGUILD-24325] Doc feedback - too many spans clarity (#1052)

* try bulleted list

* update spansdroppedblocked metrics

* update reasons for numSpansDroppedBlocked with more specific details

signalfx-org-metrics/metrics.yaml

@@ -133,7 +133,11 @@ sf.org.apm.numSpanBytesReceivedByToken:
 sf.org.apm.numSpansDroppedBlocked:
   brief: The number of spans that APM was unable to process or has dropped due to a blocked trace or too many spans in the trace.
   description: |
-    The number of spans that APM was unable to process or has dropped because the trace has a blocked trace ID or too many spans in the trace.
+    The number of spans that APM was unable to process or has dropped. A span can be dropped for the following reasons: 
+      * blockedTraceID: If any ingest endpoint reaches the 100k limit for spans in a given trace, then the trace is added to the list of blocked traces so that all the ingest endpoints block any future spans.
+      * tooManySpansInTrace: Trace submitted over 100k spans at the first ingest stage
+
+      ``sf.org.apm.numSpansDroppedBlocked`` has the following dimensions and data resolution:
 
       * Dimension(s): `orgId`
       * Data resolution: 1 second
@@ -143,7 +147,12 @@ sf.org.apm.numSpansDroppedBlocked:
 sf.org.apm.numSpansDroppedBlockedByToken:
   brief: The number of spans for a specific token that APM was unable to process or has dropped due to a blocked trace or too many spans in the trace 
   description: |
-    The number of spans for a specific token that APM was unable to process or has dropped because the trace has a blocked trace ID or too many spans in the trace.
+    The number of spans for a specific token that APM was unable to process or has dropped. A span can be
+    dropped for the following reasons: 
+      * blockedTraceID: If any ingest endpoint reaches the 100k limit for spans in a given trace, then the trace is added to the list of blocked traces so that all the ingest endpoints block any future spans.
+      * tooManySpansInTrace: Trace submitted over 100k spans at the first ingest stage
+
+      ``sf.org.apm.numSpansDroppedBlocked`` has the following dimensions and data resolution:
 
       * Dimension(s): `orgId`
       * Data resolution: 1 second
@@ -154,8 +163,14 @@ sf.org.apm.numSpansDroppedInvalid:
   brief: The number of invalid spans Splunk APM receives.
   description: |
     The number of invalid spans Splunk APM receives. A span can be
-    invalid if there is no start time, trace ID, or service associated with it,
-    or if there are too many spans in the trace.
+    invalid for the following reasons: 
+      * invalidTraceID: Trace ID isn't a 16-byte or 32-byte hex number
+      * noOperationName: No operation name was provided
+      * spanTooLarge: Span body exceeds 64KiB
+      * zeroStartTime: The start timestamp is 0
+      * zipkinV2BinaryAnnotations: Unsupported Zipkin feature
+    
+    ``sf.org.apm.numSpansDroppedInvalid`` has the following dimensions and data resolution:
 
       * Dimension(s): `orgId`
       * Data resolution: 1 second
@@ -167,8 +182,14 @@ sf.org.apm.numSpansDroppedInvalidByToken:
     token.
   description: |
     The number of invalid spans Splunk APM receives for a specific
-    access token. A span can be invalid if there is no start time, trace ID, or
-    service associated with it, or if there are too many spans in the trace.
+    access token. A span can be invalid for the following reasons: 
+      * invalidTraceID: Trace ID isn't a 16-byte or 32-byte hex number
+      * noOperationName: No operation name was provided
+      * spanTooLarge: Span body exceeds 64KiB
+      * zeroStartTime: The start timestamp is 0
+      * zipkinV2BinaryAnnotations: Unsupported Zipkin feature
+    
+    ``sf.org.apm.numSpansDroppedInvalidByToken`` has the following dimensions and data resolution:
 
       * Dimension(s): `orgId`, `tokenId`
       * Data resolution: 1 second