docs(sdks): New Span API

Author: cleptric

develop-docs/sdk/telemetry/spans/span-api.mdx

@@ -0,0 +1,61 @@
+---
+title: Span API
+---
+
+<Alert level="info">
+  This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.
+</Alert>
+
+Spans are measuring the duration of certain operations in an application.
+The topmost member of a span tree is called the root span. This span has no parent span and groups together its children with a representative name for the entire operation, such as `GET /` in case of a request to a backend application.
+
+## Creating a root span
+
+The SDK must expose a method for creating a root span. The user must be able to set certain properties on this root span, such as its name, the type of operation (`op`) and others.
+
+```js
+span = sentry.tracing.startSpan()
+	->setName('GET /')
+	->setOp('http.server')
+
+span.end()
+```
+
+## Creating nested spans
+
+To create nested spans, the SDK must expose an explicit way for a user to perform this task.
+
+Additionally, the SDK may expose alternative APIs to create nested spans, such as allowing a user to wrap an operation into a callback or apply a decorator to certain blocks. These alternative APIs must never create a root span and no-op if no parent span is present.
+
+```js
+childSpan = span.startChild()
+	->setName('authentication middleware')
+	->setOp('middleware.handle')
+	
+childSpan.end()
+```
+
+## Setting the span status
+
+A span has two statuses, `ok` and `error`. By default, the status of a span is set to `ok`.
+The SDK must allow a user to modify the status of a span.
+
+```js
+span.setStatus('error')
+```
+
+## Setting span attributes
+
+The SDK must expose a method to allow a user to set data attributes onto a span.
+These attributes should use pre-defined keys whenever possible.
+
+```js
+span.setAttribute(SpanAttributes.HTTP_METHOD, 'GET')
+span.setAttribute(SpanAttributes.HTTP_RESPONSE_STATUS_CODE, 200)
+```
+
+## Additional, optional span APIs
+
+`span.setStartTimestamp()` - overwrite the span's start time
+
+`span.setEndTimestamp()` - overwrites the span's end time

develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx

@@ -0,0 +1,28 @@
+---
+title: Span Trace Propagation
+---
+
+<Alert level="info">
+  This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.
+</Alert>
+
+## Continue an incoming trace
+
+To continue a trace from an upstream service, the SDK must expose a method to extract the traceparent and baggage information and apply these to the applicable scope.
+
+```js
+scope.setPropagationContext({
+    traceparent: request.headers.SENTRY_TRACE,
+    baggage: request.headers.SENTRY_BAGGAGE,
+})
+```
+Newly created root spans should now contain these properties, such as `trace_id` and `parent_span_id`.
+
+## Continue an outgoing trace
+
+To propagate a trace to a downstream service, the SDK must expose methods to fetch the required information to allow the next service to continue the trace.
+
+```js
+traceparent = scope.getTraceparent()
+baggage = scope.getBaggage()
+```