internal/telemetry: revamp

.gitlab-ci.yml

@@ -9,8 +9,7 @@ variables:
   INDEX_FILE: index.txt
   KUBERNETES_SERVICE_ACCOUNT_OVERWRITE: dd-trace-go
   FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY: "true"
-  BENCHMARK_TARGETS: "BenchmarkStartRequestSpan|BenchmarkHttpServeTrace|BenchmarkTracerAddSpans|BenchmarkStartSpan|BenchmarkSingleSpanRetention|BenchmarkOTelApiWithCustomTags|BenchmarkInjectW3C|BenchmarkExtractW3C|BenchmarkPartialFlushing|BenchmarkGraphQL|BenchmarkSampleWAFContext|BenchmarkCaptureStackTrace|BenchmarkSetTagString|BenchmarkSetTagStringPtr|BenchmarkSetTagMetric|BenchmarkSetTagStringer|BenchmarkSerializeSpanLinksInMeta"
-
+  BENCHMARK_TARGETS: "BenchmarkStartRequestSpan|BenchmarkHttpServeTrace|BenchmarkTracerAddSpans|BenchmarkStartSpan|BenchmarkSingleSpanRetention|BenchmarkOTelApiWithCustomTags|BenchmarkInjectW3C|BenchmarkExtractW3C|BenchmarkPartialFlushing|BenchmarkGraphQL|BenchmarkSampleWAFContext|BenchmarkCaptureStackTrace|BenchmarkSetTagString|BenchmarkSetTagStringPtr|BenchmarkSetTagMetric|BenchmarkSetTagStringer|BenchmarkSerializeSpanLinksInMeta|BenchmarkLogs|BenchmarkWorstCaseScenarioFloodLogging|BenchmarkMetrics|BenchmarkWorstCaseScenarioFloodMetrics"
 include:
   - ".gitlab/benchmarks.yml"
   - ".gitlab/macrobenchmarks.yml"

internal/globalconfig/globalconfig.go

@@ -9,6 +9,7 @@ package globalconfig
 
 import (
 	"math"
+	"os"
 	"sync"
 
 	"gopkg.in/DataDog/dd-trace-go.v1/internal"
@@ -130,3 +131,18 @@ func HeaderTagsLen() int {
 func ClearHeaderTags() {
 	cfg.headersAsTags.Clear()
 }
+
+// InstrumentationInstallID returns the install ID as described in DD_INSTRUMENTATION_INSTALL_ID
+func InstrumentationInstallID() string {
+	return os.Getenv("DD_INSTRUMENTATION_INSTALL_ID")
+}
+
+// InstrumentationInstallType returns the install type as described in DD_INSTRUMENTATION_INSTALL_TYPE
+func InstrumentationInstallType() string {
+	return os.Getenv("DD_INSTRUMENTATION_INSTALL_TYPE")
+}
+
+// InstrumentationInstallTime returns the install time as described in DD_INSTRUMENTATION_INSTALL_TIME
+func InstrumentationInstallTime() string {
+	return os.Getenv("DD_INSTRUMENTATION_INSTALL_TIME")
+}

internal/newtelemetry/README.md

@@ -0,0 +1,69 @@
+# Instrumentation Telemetry Client Architecture
+
+This documentation details the current architecture of the Instrumentation Telemetry Client of dd-trace-go and was are its capabilities.
+For an API documentation, please refer to the [api.go](https://github.com/DataDog/dd-trace-go/blob/main/internal/telemetry/api.go) file content.
+
+Please, make sure to read the [Specification Documentation](https://github.com/DataDog/instrumentation-telemetry-api-docs/tree/main) before reading this document.
+
+### Data Flow
+
+```mermaid
+flowchart TD
+    linkStyle default interpolate basis
+    globalclient@{ shape: circle } -->|client == nil| recorder
+    globalclient -->|client != nil| client
+    recorder@{ shape: cyl } --> client@{ shape: circle }
+
+    subgraph datasources
+        integrations@{ shape: cyl }
+        configuration@{ shape: cyl }
+        dependencies@{ shape: cyl }
+        products@{ shape: cyl }
+        logs@{ shape: cyl }
+        metrics@{ shape: cyl }
+    end
+
+    client --> datasources
+
+    subgraph mapper
+        direction LR
+        app-started -->
+        default[message-batch<div>heartbeat<div>extended-heartbeat] --> app-closing
+    end
+
+    flush@{ shape:rounded }
+
+    queue@{ shape: cyl } --> flush
+
+    datasources -..->|at flush| mapper --> flush
+    flush -->|if writer fails| queue
+
+    flush --> writer
+
+    writer --> agent@{ shape: das }
+    writer --> backend@{ shape: stadium }
+    agent --> backend
+```
+
+### Low Level Components
+
+- **`RingQueue[T]`**: The ring queue is an arbitrary data structure that support growing buffers, a buffer pool, and overflow. It is used as a backend data structure for the payload queue, the recorder and distribution metrics.
+- **`Recorder[T]`**: The recorder is a `RingBuffer[func(T)]` that stores functions until the actual value `T` has been created when calling `Replay(T)` dequeues all functions from the recorder and applies them to the value `T`. By default, it can store 512 functions at most.
+- **`Range[T]`**: Simple data structure that stores a start and end value, a minimum and maximum interval and has utils functions to help managing ranges.
+- **`SyncMap[K, V]`**: Typed version of `sync.Map`
+- **`SyncPool[T]`**: Typed version of `sync.Pool`
+
+### High Level Components
+
+- **GlobalClient**: The global client is a singleton that is used to access the client instance. It is used to create a new client instance if it does not exist yet. It is also used to access the client instance if it already exists. The global client recorder record calls to the clients until the `StartApp` function is called
+- **Client**: The actual `Client` interface implementation. It's main job is to steer data to its corresponding data source. Other than that it actually manages the config of the client and gather data from the data sources to call `Flush` with it.
+- **Data Sources**: Each data source implement the `dataSource` interface that has the method `Payload() transport.Payload` that is supposed to flush all data from the data source and make it into a payload ready to be serialized and sent to the backend.
+  - **Integrations**: The integrations data source is responsible for creating the [`app-integrations-change`](https://github.com/DataDog/instrumentation-telemetry-api-docs/blob/main/GeneratedDocumentation/ApiDocs/v2/SchemaDocumentation/Schemas/app_integrations_change.md) payload. A very simple slice and mutex is used as backing store.
+  - **Configuration**: The configuration data source is responsible for creating the [`app-client-configuration-change`](https://github.com/DataDog/instrumentation-telemetry-api-docs/blob/main/GeneratedDocumentation/ApiDocs/v2/SchemaDocumentation/Schemas/app_client_configuration_change.md) payload. A map and mutex is used as backing store.
+  - **Dependencies**: The dependencies data source is responsible for gathering data [`app-dependencies-loaded`](https://github.com/DataDog/instrumentation-telemetry-api-docs/blob/main/GeneratedDocumentation/ApiDocs/v2/SchemaDocumentation/Schemas/app_dependencies_loaded.md) payload. No public API is available for this as this is does in-house with the `ClientConfig.DependencyLoader` function output.
+  - **Product**: The product data source is responsible for gathering data [`app-product-change`](https://github.com/DataDog/instrumentation-telemetry-api-docs/blob/main/GeneratedDocumentation/ApiDocs/v2/SchemaDocumentation/Schemas/app_product_change.md) payload. A map and mutex is used as backing store.
+  - **Metrics**: The metrics data source is responsible for gathering data for the [`generate-metrics`](https://github.com/DataDog/instrumentation-telemetry-api-docs/blob/main/GeneratedDocumentation/ApiDocs/v2/SchemaDocumentation/Schemas/generate_metrics.md) payload. A `SyncMap[metrickey, metricHandle]` is used as backing store. More on that in the metrics specific section
+  - **Distributions**: The distributions data source is responsible for gathering data for the [`distributions`](https://github.com/DataDog/instrumentation-telemetry-api-docs/blob/main/GeneratedDocumentation/ApiDocs/v2/SchemaDocumentation/Schemas/distributions.md) payload. A `SyncMap[distributionkey, distributionHandle]` is used as backing store. More on that in the metrics specific section
+  - **Logs**: The logs data source is responsible for gathering data for the [`generate-logs`](https://github.com/DataDog/instrumentation-telemetry-api-docs/blob/main/GeneratedDocumentation/ApiDocs/v2/SchemaDocumentation/Schemas/logs.md) payload. A `SyncMap[logkey, logValue]` is used as backing store. More on that in the logs specific section.
+- **Mapper**: The mapper is also responsible for creating the `app-started`, `app-closing`, `heartbeat`, `extended-heartbeat` and `message-batch` payloads from the data sources that needs data from other payloads but not from the API user. The mapper already return another mapper that will be used in the next call to `Flush`.
+- **Writer**: The writer is responsible for sending the payload to the backend. It is a simple interface that has a `Write` method that receives a `transport.Payload` and returns statistics about the write operation.

internal/newtelemetry/api.go

@@ -0,0 +1,165 @@
+// Unless explicitly stated otherwise all files in this repository are licensed
+// under the Apache License Version 2.0.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2024 Datadog, Inc.
+
+// Package newtelemetry provides a telemetry client that is thread-safe burden-less telemetry client following the specification of the instrumentation telemetry from Datadog.
+// Specification here: https://github.com/DataDog/instrumentation-telemetry-api-docs/tree/main
+//
+// The telemetry package has 6 main capabilities:
+//   - Metrics: Support for [Count], [Rate], [Gauge], [Distribution] metrics.
+//   - Logs: Support Debug, Warn, Error logs with tags and stack traces via the subpackage [log] or the [Log] function.
+//   - Product: Start, Stop and Startup errors reporting to the backend
+//   - App Config: Register and change the configuration of the application and declare its origin
+//   - Integration: Loading and errors
+//   - Dependencies: Sending all the dependencies of the application to the backend (for SCA purposes for example)
+//
+// Each of these capabilities is exposed through the [Client] interface but mainly through the package level functions.
+// that mirror and call the global client that is started through the [StartApp] function.
+//
+// Before the [StartApp] function is called, all called to the global client will be recorded and replay
+// when the [StartApp] function is called synchronously. The telemetry client is allowed to record at most 512 calls.
+//
+// At the end of the app lifetime. If [tracer.Stop] is called, the client should be stopped with the [StopApp] function.
+// For all data to be flushed to the backend appropriately.
+//
+// Note: No public API is available for the dependencies payloads as this is does in-house with the `ClientConfig.DependencyLoader` function output.
+package newtelemetry
+
+import (
+	"io"
+
+	"gopkg.in/DataDog/dd-trace-go.v1/internal/newtelemetry/internal/transport"
+)
+
+// Namespace describes a product to distinguish telemetry coming from
+// different products used by the same application
+type Namespace = transport.Namespace
+
+//goland:noinspection GoVarAndConstTypeMayBeOmitted  Goland is having a hard time with the following const block, it keeps deleting the type
+const (
+	NamespaceGeneral      Namespace = transport.NamespaceGeneral
+	NamespaceTracers      Namespace = transport.NamespaceTracers
+	NamespaceProfilers    Namespace = transport.NamespaceProfilers
+	NamespaceAppSec       Namespace = transport.NamespaceAppSec
+	NamespaceIAST         Namespace = transport.NamespaceIAST
+	NamespaceCIVisibility Namespace = transport.NamespaceCIVisibility
+	NamespaceMLOps        Namespace = transport.NamespaceMLOps
+	NamespaceRUM          Namespace = transport.NamespaceRUM
+)
+
+// Origin describes the source of a configuration change
+type Origin = transport.Origin
+
+//goland:noinspection GoVarAndConstTypeMayBeOmitted Goland is having a hard time with the following const block, it keeps deleting the type
+const (
+	OriginDefault      Origin = transport.OriginDefault
+	OriginCode         Origin = transport.OriginCode
+	OriginDDConfig     Origin = transport.OriginDDConfig
+	OriginEnvVar       Origin = transport.OriginEnvVar
+	OriginRemoteConfig Origin = transport.OriginRemoteConfig
+)
+
+// LogLevel describes the level of a log message
+type LogLevel = transport.LogLevel
+
+//goland:noinspection GoVarAndConstTypeMayBeOmitted Goland is having a hard time with the following const block, it keeps deleting the type
+const (
+	LogDebug LogLevel = transport.LogLevelDebug
+	LogWarn  LogLevel = transport.LogLevelWarn
+	LogError LogLevel = transport.LogLevelError
+)
+
+// MetricHandle can be used to submit different values for the same metric.
+// MetricHandle is used to reduce lock contention when submitting metrics.
+// This can also be used ephemerally to submit a single metric value like this:
+//
+//	telemetry.metric(telemetry.Appsec, "my-count", map[string]string{"tag1": "true", "tag2": "1.0"}).Submit(1.0)
+type MetricHandle interface {
+	// Submit submits a value to the metric handle.
+	Submit(value float64)
+	// Get returns the last value submitted to the metric handle.
+	Get() float64
+}
+
+// Integration is an integration that is configured to be traced.
+type Integration struct {
+	// Name is an arbitrary string that must stay constant for the integration.
+	Name string
+	// Version is the version of the integration/dependency that is being loaded.
+	Version string
+	// Error is the error that occurred while loading the integration. If this field is specified, the integration is
+	// considered to be having been forcefully disabled because of the error.
+	Error string
+}
+
+// Configuration is a key-value pair that is used to configure the application.
+type Configuration struct {
+	// Key is the key of the configuration.
+	Name string
+	// Value is the value of the configuration. Need to be json serializable.
+	Value any
+	// Origin is the source of the configuration change.
+	Origin Origin
+}
+
+// LogOption is a function that modifies the log message that is sent to the telemetry.
+type LogOption func(key *loggerKey, value *loggerValue)
+
+// Client constitutes all the functions available concurrently for the telemetry users. All methods are thread-safe
+// This is an interface for easier testing but all functions will be mirrored at the package level to call
+// the global client.
+type Client interface {
+	io.Closer
+
+	// Count obtains the metric handle for the given parameters, or creates a new one if none was created just yet.
+	// Tags cannot contain commas.
+	Count(namespace Namespace, name string, tags []string) MetricHandle
+
+	// Rate obtains the metric handle for the given parameters, or creates a new one if none was created just yet.
+	// Tags cannot contain commas.
+	Rate(namespace Namespace, name string, tags []string) MetricHandle
+
+	// Gauge obtains the metric handle for the given parameters, or creates a new one if none was created just yet.
+	// Tags cannot contain commas.
+	Gauge(namespace Namespace, name string, tags []string) MetricHandle
+
+	// Distribution obtains the metric handle for the given parameters, or creates a new one if none was created just yet.
+	// Tags cannot contain commas.
+	Distribution(namespace Namespace, name string, tags []string) MetricHandle
+
+	// Log sends a telemetry log at the desired level with the given text and options.
+	// Options include sending key-value pairs as tags, and a stack trace frozen from inside the Log function.
+	Log(level LogLevel, text string, options ...LogOption)
+
+	// ProductStarted declares a product to have started at the customer’s request
+	ProductStarted(product Namespace)
+
+	// ProductStopped declares a product to have being stopped by the customer
+	ProductStopped(product Namespace)
+
+	// ProductStartError declares that a product could not start because of the following error
+	ProductStartError(product Namespace, err error)
+
+	// RegisterAppConfig adds a key value pair to the app configuration and send the change to telemetry
+	// value has to be json serializable and the origin is the source of the change.
+	RegisterAppConfig(key string, value any, origin Origin)
+
+	// RegisterAppConfigs adds a list of key value pairs to the app configuration and sends the change to telemetry.
+	// Same as AddAppConfig but for multiple values.
+	RegisterAppConfigs(kvs ...Configuration)
+
+	// MarkIntegrationAsLoaded marks an integration as loaded in the telemetry
+	MarkIntegrationAsLoaded(integration Integration)
+
+	// Flush closes the client and flushes any remaining data.
+	Flush()
+
+	// AppStart sends the telemetry necessary to signal that the app is starting.
+	// Preferred use via [StartApp] package level function
+	AppStart()
+
+	// AppStop sends the telemetry necessary to signal that the app is stopping.
+	// Preferred use via [StopApp] package level function
+	AppStop()
+}