libdatadog 35.0.0.1.0 → 36.0.0.1.0

data/vendor/libdatadog-36.0.0/x86_64-linux/include/datadog/data-pipeline.h

@@ -0,0 +1,391 @@
+// Copyright 2021-Present Datadog, Inc. https://www.datadoghq.com/
+// SPDX-License-Identifier: Apache-2.0
+
+
+#ifndef DDOG_DATA_PIPELINE_H
+#define DDOG_DATA_PIPELINE_H
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include "common.h"
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+/**
+ * Frees `error` and all its contents. After being called error will not point to a valid memory
+ * address so any further actions on it could lead to undefined behavior.
+ */
+void ddog_trace_exporter_error_free(struct ddog_TraceExporterError *error);
+
+/**
+ * Return a borrowed view of the response body.  The returned slice is
+ * only valid as long as `response` is alive.  Returns an empty slice
+ * when `response` is null or the body is absent.
+ */
+ddog_ByteSlice ddog_trace_exporter_response_get_body(const struct ddog_TraceExporterResponse *response);
+
+/**
+ * Free `response` and all its contents. After being called response will not point to a valid
+ * memory address so any further actions on it could lead to undefined behavior.
+ */
+void ddog_trace_exporter_response_free(struct ddog_TraceExporterResponse *response);
+
+void ddog_trace_exporter_config_new(struct ddog_TraceExporterConfig **out_handle);
+
+/**
+ * Frees TraceExporterConfig handle internal resources.
+ */
+void ddog_trace_exporter_config_free(struct ddog_TraceExporterConfig *handle);
+
+/**
+ * Sets traces destination.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_url(struct ddog_TraceExporterConfig *config,
+                                                                   ddog_CharSlice url);
+
+/**
+ * Sets tracer's version to be included in the headers request.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_tracer_version(struct ddog_TraceExporterConfig *config,
+                                                                              ddog_CharSlice version);
+
+/**
+ * Sets tracer's language to be included in the headers request.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_language(struct ddog_TraceExporterConfig *config,
+                                                                        ddog_CharSlice lang);
+
+/**
+ * Sets tracer's language version to be included in the headers request.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_lang_version(struct ddog_TraceExporterConfig *config,
+                                                                            ddog_CharSlice version);
+
+/**
+ * Sets tracer's language interpreter to be included in the headers request.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_lang_interpreter(struct ddog_TraceExporterConfig *config,
+                                                                                ddog_CharSlice interpreter);
+
+/**
+ * Sets hostname information to be included in the headers request.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_hostname(struct ddog_TraceExporterConfig *config,
+                                                                        ddog_CharSlice hostname);
+
+/**
+ * Sets environment information to be included in the headers request.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_env(struct ddog_TraceExporterConfig *config,
+                                                                   ddog_CharSlice env);
+
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_version(struct ddog_TraceExporterConfig *config,
+                                                                       ddog_CharSlice version);
+
+/**
+ * Sets service name to be included in the headers request.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_service(struct ddog_TraceExporterConfig *config,
+                                                                       ddog_CharSlice service);
+
+/**
+ * Enables health metrics emission.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_enable_health_metrics(struct ddog_TraceExporterConfig *config,
+                                                                                 bool is_enabled);
+
+/**
+ * Enables telemetry metrics.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_enable_telemetry(struct ddog_TraceExporterConfig *config,
+                                                                            const struct ddog_TelemetryClientConfig *telemetry_cfg);
+
+/**
+ * Set client-side stats computation status.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_compute_stats(struct ddog_TraceExporterConfig *config,
+                                                                             bool is_enabled);
+
+/**
+ * Sets `Datadog-Client-Computed-Stats` header to `true`.
+ * This indicates that the upstream system has already computed the stats,
+ * and no further stats computation should be performed.
+ *
+ * <div class="warning">
+ * This method must not be used when `compute_stats` is enabled, as it could
+ * result in duplicate stats computation.
+ * </div>
+ *
+ * A common use case is in Application Security Monitoring (ASM) scenarios:
+ * when APM is disabled but ASM is enabled, setting this header to `true`
+ * ensures that no stats are computed at any level (exporter or agent).
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_client_computed_stats(struct ddog_TraceExporterConfig *config,
+                                                                                     bool client_computed_stats);
+
+/**
+ * Sets the process tags to be included in the stats payload.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_process_tags(struct ddog_TraceExporterConfig *config,
+                                                                            ddog_CharSlice process_tags);
+
+/**
+ * Sets the `X-Datadog-Test-Session-Token` header. Only used for testing with the test agent.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_test_session_token(struct ddog_TraceExporterConfig *config,
+                                                                                  ddog_CharSlice token);
+
+/**
+ * Sets the timeout in ms for all agent's connections.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_connection_timeout(struct ddog_TraceExporterConfig *config,
+                                                                                  uint64_t timeout_ms);
+
+/**
+ * Sets a shared runtime for the TraceExporter to use for background workers.
+ *
+ * `handle` must have been initialized with [`ddog_shared_runtime_new`].
+ *
+ * When set, the exporter will use the provided runtime instead of creating its own.
+ * This allows multiple exporters (or other components) to share a single runtime.
+ * The config holds a clone of the `Arc` (increments the strong count), so the
+ * original handle remains valid and must still be freed with
+ * [`ddog_shared_runtime_free`].
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_shared_runtime(struct ddog_TraceExporterConfig *config,
+                                                                              struct ddog_SharedRuntime *handle);
+
+/**
+ * Enables OTLP HTTP/JSON export and sets the endpoint URL.
+ *
+ * When set, traces are sent to this URL in OTLP HTTP/JSON format instead of the Datadog
+ * agent. The host language is responsible for resolving the endpoint from its configuration
+ * (e.g. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) before calling this function.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_config_set_otlp_endpoint(struct ddog_TraceExporterConfig *config,
+                                                                             ddog_CharSlice url);
+
+/**
+ * Create a new TraceExporter instance.
+ *
+ * When an OTLP endpoint is configured via `TraceExporterConfig`, the exporter sends traces in
+ * OTLP HTTP/JSON to that endpoint instead of the Datadog agent. The same payload (e.g.
+ * MessagePack) is passed to `ddog_trace_exporter_send`; the library decodes and converts to
+ * OTLP when OTLP is enabled.
+ *
+ * # Arguments
+ *
+ * * `out_handle` - The handle to write the TraceExporter instance in.
+ * * `config` - The configuration used to set up the TraceExporter handle.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_new(ddog_TraceExporter **out_handle,
+                                                        const struct ddog_TraceExporterConfig *config);
+
+/**
+ * Free the TraceExporter instance.
+ *
+ * # Arguments
+ *
+ * * handle - The handle to the TraceExporter instance.
+ */
+void ddog_trace_exporter_free(ddog_TraceExporter *handle);
+
+/**
+ * Send traces to the Datadog Agent.
+ *
+ * # Arguments
+ *
+ * * `handle` - The handle to the TraceExporter instance.
+ * * `trace` - The traces to send to the Datadog Agent in the input format used to create the
+ *   TraceExporter. The memory for the trace must be valid for the life of the call to this
+ *   function.
+ * * `trace_count` - The number of traces to send to the Datadog Agent.
+ * * `response_out` - Optional handle to store a pointer to the agent response information.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_send(const ddog_TraceExporter *handle,
+                                                         ddog_ByteSlice trace,
+                                                         struct ddog_TraceExporterResponse **response_out);
+
+/**
+ * Create a new span with all scalar fields set.
+ *
+ * String fields are copied from the provided slices.  The `meta` and
+ * `metrics` maps start empty; use [`ddog_tracer_span_set_meta`] and
+ * [`ddog_tracer_span_set_metric`] to populate them.
+ *
+ * # Safety
+ *
+ * `out_handle` must point to valid, writable memory for a `Box<TracerSpan>`.
+ * All `CharSlice` fields in `fields` must point to valid memory for their
+ * stated length.
+ */
+struct ddog_TraceExporterError *ddog_tracer_span_new(ddog_TracerSpan **out_handle,
+                                                     const struct ddog_TracerSpanFields *fields);
+
+/**
+ * Free a `TracerSpan` and all its contents.
+ *
+ * After this call the handle is invalid and must not be reused.
+ *
+ * # Safety
+ *
+ * `handle` must have been created by [`ddog_tracer_span_new`] and must not
+ * be used after this call.
+ */
+void ddog_tracer_span_free(ddog_TracerSpan *handle);
+
+/**
+ * Add or overwrite a string tag (`meta`) on the span.
+ *
+ * Both `key` and `value` are copied into the span.
+ *
+ * # Safety
+ *
+ * `handle` must be a valid pointer to a `TracerSpan`.
+ * `key` and `value` must point to valid UTF-8 memory.
+ */
+struct ddog_TraceExporterError *ddog_tracer_span_set_meta(ddog_TracerSpan *handle,
+                                                          ddog_CharSlice key,
+                                                          ddog_CharSlice value);
+
+/**
+ * Add or overwrite a numeric tag (`metric`) on the span.
+ *
+ * The `key` is copied into the span.
+ *
+ * # Safety
+ *
+ * `handle` must be a valid pointer to a `TracerSpan`.
+ * `key` must point to valid UTF-8 memory.
+ */
+struct ddog_TraceExporterError *ddog_tracer_span_set_metric(ddog_TracerSpan *handle,
+                                                            ddog_CharSlice key,
+                                                            double value);
+
+/**
+ * Create a new empty trace chunks container.
+ *
+ * `capacity` is a hint for the expected number of chunks; pass 0 if
+ * unknown.
+ *
+ * # Safety
+ *
+ * `out_handle` must point to valid, writable memory for a
+ * `Box<TracerTraceChunks>`.
+ */
+struct ddog_TraceExporterError *ddog_tracer_trace_chunks_new(uintptr_t capacity,
+                                                             ddog_TracerTraceChunks **out_handle);
+
+/**
+ * Free a trace chunks container and all its contents.
+ *
+ * After this call the handle is invalid and must not be reused.
+ *
+ * # Safety
+ *
+ * `handle` must have been created by [`ddog_tracer_trace_chunks_new`].
+ */
+void ddog_tracer_trace_chunks_free(ddog_TracerTraceChunks *handle);
+
+/**
+ * Start a new chunk (trace) inside the container.
+ *
+ * Subsequent [`ddog_tracer_trace_chunks_push_span`] calls will append
+ * spans to this chunk until the next `begin_chunk` call.
+ *
+ * `capacity` is a hint for the expected number of spans in this chunk;
+ * pass 0 if unknown.
+ *
+ * # Safety
+ *
+ * `handle` must be a valid pointer to a `TracerTraceChunks`.
+ */
+struct ddog_TraceExporterError *ddog_tracer_trace_chunks_begin_chunk(ddog_TracerTraceChunks *handle,
+                                                                     uintptr_t capacity);
+
+/**
+ * Move a span into the current (last) chunk, consuming the span handle.
+ *
+ * A chunk must have been started with
+ * [`ddog_tracer_trace_chunks_begin_chunk`] before calling this function.
+ *
+ * # Safety
+ *
+ * * `handle` must be a valid pointer to a `TracerTraceChunks`.
+ * * `span` is consumed and must not be used after this call.
+ */
+struct ddog_TraceExporterError *ddog_tracer_trace_chunks_push_span(ddog_TracerTraceChunks *handle,
+                                                                   ddog_TracerSpan *span);
+
+/**
+ * Create a new cancellation token.
+ *
+ * The returned token must be freed with
+ * [`ddog_trace_exporter_cancel_token_drop`].
+ */
+ddog_TraceExporterCancelToken *ddog_trace_exporter_cancel_token_new(void);
+
+/**
+ * Cancel a cancellation token.
+ *
+ * All clones of the same token observe the cancellation. If a
+ * [`ddog_trace_exporter_send_trace_chunks`] call is using this token at the
+ * time of cancellation, that send stops waiting for the agent at its next
+ * await point and returns an error; the trace chunks it was sending may be
+ * lost.
+ *
+ * Cancellation only affects a send that is in progress. If no send is using
+ * the token, cancelling it has no immediate effect: a send started afterwards
+ * with an already-cancelled token returns an error without contacting the
+ * agent, and a token cancelled after its send has already finished does
+ * nothing.
+ */
+void ddog_trace_exporter_cancel_token_cancel(const ddog_TraceExporterCancelToken *token);
+
+/**
+ * Free a cancellation token.
+ *
+ * After this call the token is invalid and must not be reused.
+ */
+void ddog_trace_exporter_cancel_token_drop(ddog_TraceExporterCancelToken *token);
+
+/**
+ * Send trace chunks through a [`TraceExporter`], consuming the chunks.
+ *
+ * This calls `TraceExporter::send_trace_chunks` which processes stats,
+ * serializes in the configured output format, and sends to the agent
+ * with retry logic.
+ *
+ * When `cancel` is non-null, cancelling that token (via
+ * [`ddog_trace_exporter_cancel_token_cancel`]) while the send is in progress
+ * aborts the in-flight request and returns an error with code
+ * [`ExporterErrorCode::IoError`]. Cancellation is cooperative: it only takes
+ * effect while a request is actually in flight. A token that is already
+ * cancelled when the send starts makes this function return that error
+ * immediately, and cancelling after the send has finished has no effect.
+ * Cancelling an in-flight send may cause the trace chunks being sent to be
+ * lost.
+ *
+ * On success, if `response_out` is non-null, a heap-allocated
+ * [`ExporterResponse`] is written there.  The caller owns it and must
+ * free it with `ddog_trace_exporter_response_free`.
+ *
+ * # Safety
+ *
+ * * `chunks` is consumed and must not be used after this call.
+ * * If `response_out` is non-null it must point to valid writable memory for a
+ *   `Box<ExporterResponse>`.
+ */
+struct ddog_TraceExporterError *ddog_trace_exporter_send_trace_chunks(const ddog_TraceExporter *exporter,
+                                                                      ddog_TracerTraceChunks *chunks,
+                                                                      struct ddog_TraceExporterResponse **response_out,
+                                                                      const ddog_TraceExporterCancelToken *cancel);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif  // __cplusplus
+
+#endif  /* DDOG_DATA_PIPELINE_H */