feat: spec compliant sampling result support (open-telemetry#1058)

api/src/index.ts

@@ -39,6 +39,7 @@ export * from './trace/NoopSpan';
 export * from './trace/NoopTracer';
 export * from './trace/NoopTracerProvider';
 export * from './trace/Sampler';
+export * from './trace/SamplingResult';
 export * from './trace/span_context';
 export * from './trace/span_kind';
 export * from './trace/span';

api/src/trace/Sampler.ts

@@ -15,6 +15,10 @@
  */
 
 import { SpanContext } from './span_context';
+import { SpanKind } from './span_kind';
+import { Attributes } from './attributes';
+import { Link } from './link';
+import { SamplingResult } from './SamplingResult';
 
 /**
  * This interface represent a sampler. Sampling is a mechanism to control the
@@ -25,12 +29,26 @@ export interface Sampler {
   /**
    * Checks whether span needs to be created and tracked.
    *
-   * TODO: Consider to add required arguments https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/sampling-api.md#shouldsample
-   * @param [parentContext] Parent span context. Typically taken from the wire.
+   * @param parentContext Parent span context. Typically taken from the wire.
    *     Can be null.
-   * @returns whether span should be sampled or not.
+   * @param traceId of the span to be created. It can be different from the
+   *     traceId in the {@link SpanContext}. Typically in situations when the
+   *     span to be created starts a new trace.
+   * @param spanName of the span to be created.
+   * @param spanKind of the span to be created.
+   * @param attributes Initial set of Attributes for the Span being constructed.
+   * @param links Collection of links that will be associated with the Span to
+   *     be created. Typically useful for batch operations.
+   * @returns a {@link SamplingResult}.
    */
-  shouldSample(parentContext?: SpanContext): boolean;
+  shouldSample(
+    parentContext: SpanContext | undefined,
+    traceId: string,
+    spanName: string,
+    spanKind: SpanKind,
+    attributes: Attributes,
+    links: Link[]
+  ): SamplingResult;
 
   /** Returns the sampler name or short description with the configuration. */
   toString(): string;

api/src/trace/SamplingResult.ts

@@ -0,0 +1,56 @@
+/*!
+ * Copyright 2020, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Attributes } from './attributes';
+
+/**
+ * A sampling decision that determines how a {@link Span} will be recorded
+ * and collected.
+ */
+export enum SamplingDecision {
+  /**
+   * `Span.isRecording() === false`, span will not be recorded and all events
+   * and attributes will be dropped.
+   */
+  NOT_RECORD,
+  /**
+   * `Span.isRecording() === true`, but `Sampled` flag in {@link TraceFlags}
+   * MUST NOT be set.
+   */
+  RECORD,
+  /**
+   * `Span.isRecording() === true` AND `Sampled` flag in {@link TraceFlags}
+   * MUST be set.
+   */
+  RECORD_AND_SAMPLED,
+}
+
+/**
+ * A sampling result contains a decision for a {@link Span} and additional
+ * attributes the sampler would like to added to the Span.
+ */
+export interface SamplingResult {
+  /**
+   * A sampling decision, refer to {@link SamplingDecision} for details.
+   */
+  decision: SamplingDecision;
+  /**
+   * The list of attributes returned by SamplingResult MUST be immutable.
+   * Caller may call {@link Sampler}.shouldSample any number of times and
+   * can safely cache the returned value.
+   */
+  attributes?: Readonly<Attributes>;
+}