Add signal-based overview documentation 📖

Examples/Counter/Sources/Example/Example.swift

@@ -62,7 +62,6 @@ enum Example {
             sampler: OTelConstantSampler(isOn: true),
             propagator: OTelW3CPropagator(),
             processor: processor,
-            environment: environment,
             resource: resource
         )
 

Sources/OTel/OTel.docc/Logging/logging.md

@@ -0,0 +1,16 @@
+# Logging
+
+@Metadata {
+    @TitleHeading("Signal")
+    @PageImage(purpose: card, source: "logging-card", alt: "An illustration of logs.")
+    @PageColor(green)
+    @Available("Swift OTel", introduced: "1.0")
+}
+
+OpenTelemetry logging implemented on top of Swift Log.
+
+> Warning: Logging support in Swift OTel is a work in progress. 
+
+## Overview
+
+@Image(source: "logging-card", alt: "An illustration of logs.")

Sources/OTel/OTel.docc/Metrics/metrics.md

@@ -0,0 +1,106 @@
+# Metrics
+
+@Metadata {
+    @TitleHeading("Signal")
+    @PageImage(purpose: card, source: "metrics-card", alt: "An illustration of diagrams.")
+    @PageColor(purple)
+    @Available("Swift OTel", introduced: "1.0")
+}
+
+OpenTelemetry metrics implemented on top of Swift Metrics.
+
+## Overview
+
+Metrics support in Swift OTel is implemented on top of the [Swift Metrics](https://github.com/apple/swift-metrics.git)
+library. This allows "plug-and-play" like integration with other libraries from the ecosystem, e.g.
+[Vapor](https://github.com/vapor/vapor). As long as they support `swift-metrics`, you'll be able to
+export their metrics via OpenTelemetry using Swift OTel.
+
+@Image(source: "metrics-card", alt: "An illustration of diagrams.") {
+    Two diagrams illustrating how metrics might be visualized.
+}
+
+## Getting Started
+
+The metrics API in Swift OTel consists of a couple of layers.
+
+### Metrics Factory
+
+At its core, Swift OTel metrics is implemented as a Swift Metrics
+[`MetricsFactory`](https://swiftpackageindex.com/apple/swift-metrics/2.5.0/documentation/coremetrics/metricsfactory).
+You'll use this factory to [bootstrap the `MetricsSystem`](https://swiftpackageindex.com/apple/swift-metrics/2.5.0/documentation/coremetrics#Selecting-a-metrics-backend-implementation-applications-only),
+Once bootstrapped, any metrics you create manually and the ones your dependencies emit are ready to be exported via
+[OTLP](https://opentelemetry.io/docs/specs/otlp/) (OpenTelemetry Protocol).
+
+### Metrics Reader
+
+``OTelPeriodicExportingMetricsReader`` periodically reads metrics and forwards them to an ``OTelMetricExporter``.
+It also conforms to the
+[`Service`](https://swiftpackageindex.com/swift-server/swift-service-lifecycle/2.6.0/documentation/servicelifecycle/service)
+protocol from Swift ServiceLifecycle and **must be kept running for the lifetime of your application**.
+
+> See Also: Please read the `OTLPGRPC` documentation to learn about `OTLPGRPCMetricExporter`,
+the ``OTelMetricExporter`` implementation sending metrics via gRPC to an OTel collector of choice.   
+
+### Metrics Registry
+
+``OTelMetricRegistry`` acts as the glue between ``OTLPMetricsFactory`` and ``OTelPeriodicExportingMetricsReader``,
+storing metrics produced via Swift Metrics in-memory, to be read by the periodic reader and thus exported.
+
+### Complete setup
+
+> Tip: This code snippet assumes two variables: `environment` and `resource`.
+> Check out <doc:resource-detection> to learn more about them.
+
+```swift
+import OTel
+import OTLPGRPC
+
+let registry = OTelMetricRegistry()
+
+// create the periodic reader exporting via gRPC
+let reader = OTelPeriodicExportingMetricsReader(
+    resource: resource,
+    producer: registry,
+    exporter: try OTLPGRPCMetricExporter(configuration: .init(environment: environment)),
+    configuration: .init(environment: environment)
+)
+
+// bootstrap the metrics system
+MetricsSystem.bootstrap(OTLPMetricsFactory(registry: registry))
+
+// run the reader as part of your ServiceGroup 
+let serviceGroup = ServiceGroup(services: [reader])
+try await serviceGroup.run()
+```
+
+## Sample Code
+
+A collection of Swift OTel examples that make use of Metrics.
+
+@Links(visualStyle: detailedGrid) {
+    - <doc:server-sample>
+}
+
+## Topics
+
+- ``OTLPMetricsFactory``
+- ``OTelMetricRegistry``
+- ``OTelMetricProducer``
+- ``OTelPeriodicExportingMetricsReader``
+- ``OTelPeriodicExportingMetricsReaderConfiguration``
+- ``OTelMetricExporter``
+- ``OTelMetricExporterAlreadyShutDownError``
+- ``OTelMultiplexMetricExporter``
+- ``OTelConsoleMetricExporter``
+- ``OTelAggregationTemporality``
+- ``OTelAttribute``
+- ``OTelGauge``
+- ``OTelHistogram``
+- ``OTelHistogramDataPoint``
+- ``OTelInstrumentationScope``
+- ``OTelMetricPoint``
+- ``OTelNumberDataPoint``
+- ``OTelResourceMetrics``
+- ``OTelScopeMetrics``
+- ``OTelSum``

Sources/OTel/OTel.docc/Sample Code/Counter/counter-sample.md

@@ -8,6 +8,12 @@
 
 A service that infinitely increments a counter with randomized delays, instrumented using Swift OTel.
 
+## Used signals
+
+@Links(visualStyle: list) {
+    - <doc:tracing>
+}
+
 ## Overview
 
 Each increment to the counter is instrumented by a span, as shown in the screenshot below.

Sources/OTel/OTel.docc/Sample Code/Server/server-sample.md

@@ -2,12 +2,19 @@
 
 @Metadata {
     @PageKind(sampleCode)
-    @CallToAction(purpose: link, url: "https://github.com/slashmo/swift-otel/blob/main/Examples/Counter")
+    @CallToAction(purpose: link, url: "https://github.com/slashmo/swift-otel/blob/main/Examples/Server")
     @Available("Swift", introduced: 5.9)
 }
 
 An HTTP server that uses middleware to emit traces and metrics for each HTTP request.
 
+## Used signals
+
+@Links(visualStyle: list) {
+    - <doc:metrics>
+    - <doc:tracing>
+}
+
 ## Overview
 
 This example package configures and starts a Hummingbird HTTP server along with