Add RecordLink for Span.

semantic_conventions/trace/link.yaml

@@ -0,0 +1,29 @@
+groups:
+  - id: trace-link
+    type: event
+    prefix: link
+    brief: >
+      This document defines the shared attributes used to
+      report a soft link associated with a span.
+    attributes:
+      - id: traceid
+        type: string
+        brief: >
+          The lowercase hex encoded trace id, as
+          [retrieved](../api.md#retrieving-the-traceid-and-spanid)
+          by `SpanContext`.
+        examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28'
+      - id: spanid
+        type: string
+        brief: >
+          The lowercase hex encoded span id, as
+          [retrieved](../api.md#retrieving-the-traceid-and-spanid)
+          by `SpanContext`.
+        examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28'
+      - id: tracestate
+        type: string
+        brief: >
+          The trace state, as specified in the
+          [API](../api.md#tracestate).
+        examples: 'congo=t61rcWkgMzE'
+

specification/trace/api.md

@@ -35,6 +35,7 @@
     + [UpdateName](#updatename)
     + [End](#end)
     + [Record Exception](#record-exception)
+    + [Record Link](#record-link)
   * [Span lifetime](#span-lifetime)
   * [Wrapping a SpanContext in a Span](#wrapping-a-spancontext-in-a-span)
 - [SpanKind](#spankind)
@@ -691,6 +692,26 @@ Note: `RecordException` may be seen as a variant of `AddEvent` with
 additional exception-specific parameters and all other parameters being optional
 (because they have defaults from the exception semantic convention).
 
+#### Record Link
+
+To facilitate registering `Link` relationships after a `Span` has been already
+created, languages SHOULD provide an `RecordLink` method. This is a specialized
+variant of [`AddEvent`](#add-events), so for anything not specified here, the same
+requirements as for `AddEvent` apply.
+
+The method MUST record a `Link` as an `Event` with the conventions outlined in
+the [link semantic conventions](semantic_conventions/links.md) document.
+The minimum required argument SHOULD be no more than only a `SpanContext`.
+
+If `RecordLink` is provided, the method MUST accept an optional parameter
+to provide any additional event attributes
+(this SHOULD be done in the same way as for the `AddEvent` method).
+If attributes with the same name would be generated by the method already,
+the additional attributes take precedence.
+
+Note: `RecordLink` may be seen as a variant of `AddEvent` with
+additional link-specific parameters.
+
 ### Span lifetime
 
 Span lifetime represents the process of recording the start and the end

specification/trace/semantic_conventions/links.md

@@ -0,0 +1,45 @@
+# Semantic Conventions for Links
+
+**Status**: [Experimental](../../document-status.md)
+
+This document defines semantic conventions for recording soft
+links.
+
+<!-- toc -->
+
+- [Recording a Link](#recording-a-link)
+- [Attributes](#attributes)
+
+<!-- tocstop -->
+
+## Recording a Link
+
+A `Link` SHOULD be recorded as an `Event` on the span during which it occurred.
+The name of the event MUST be `"link"`.
+
+A typical template for an instrumentation implementing this semantic convention
+using an [API-provided `recordLink` method](../api.md#record-link)
+could look like this (pseudo-Java):
+
+```java
+Span span = myTracer.startSpan(/*...*/);
+// Code that does actual work which the Span represents.
+
+SpanContext producerSpanContext = getProducerSpanContext();
+span.recordLink(producerSpanContext, Attributes.of("messaging.source.kind", "queue"));
+```
+
+## Attributes
+
+The table below indicates which attributes should be added to the `Event` and
+their types.
+
+<!-- semconv trace-link -->
+The event name MUST be `link`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `link.traceid` | string | The lowercase hex encoded trace id, as [retrieved](../api.md#retrieving-the-traceid-and-spanid) by `SpanContext`. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended |
+| `link.spanid` | string | The lowercase hex encoded span id, as [retrieved](../api.md#retrieving-the-traceid-and-spanid) by `SpanContext`. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended |
+| `link.tracestate` | string | The trace state, as specified in the [API](../api.md#tracestate). | `congo=t61rcWkgMzE` | Recommended |
+<!-- endsemconv -->