libdatadog 30.0.0.1.0 → 35.0.0.1.0

data/vendor/libdatadog-35.0.0/x86_64-linux/include/datadog/profiling.h

@@ -0,0 +1,1130 @@
+// Copyright 2021-Present Datadog, Inc. https://www.datadoghq.com/
+// SPDX-License-Identifier: Apache-2.0
+
+
+#ifndef DDOG_PROFILING_H
+#define DDOG_PROFILING_H
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+// Forward declarations for types used in common.h to avoid circular dependencies
+#include "common.h"
+struct TokioCancellationToken;
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+extern LIBDD_DLLIMPORT const ddog_prof_StringId ddog_INTERNED_EMPTY_STRING;
+
+/**
+ * A StringId that represents the empty string.
+ * This is always available in every string set and can be used without
+ * needing to insert it into a string set.
+ */
+extern LIBDD_DLLIMPORT const ddog_prof_StringId2 DDOG_PROF_STRINGID2_EMPTY;
+
+/**
+ * A StringId that represents the string "end_timestamp_ns".
+ * This is always available in every string set and can be used without
+ * needing to insert it into a string set.
+ */
+extern LIBDD_DLLIMPORT const ddog_prof_StringId2 DDOG_PROF_STRINGID2_END_TIMESTAMP_NS;
+
+/**
+ * A StringId that represents the string "local root span id".
+ * This is always available in every string set and can be used without
+ * needing to insert it into a string set.
+ */
+extern LIBDD_DLLIMPORT const ddog_prof_StringId2 DDOG_PROF_STRINGID2_LOCAL_ROOT_SPAN_ID;
+
+/**
+ * A StringId that represents the string "trace endpoint".
+ * This is always available in every string set and can be used without
+ * needing to insert it into a string set.
+ */
+extern LIBDD_DLLIMPORT const ddog_prof_StringId2 DDOG_PROF_STRINGID2_TRACE_ENDPOINT;
+
+/**
+ * A StringId that represents the string "span id".
+ * This is always available in every string set and can be used without
+ * needing to insert it into a string set.
+ */
+extern LIBDD_DLLIMPORT const ddog_prof_StringId2 DDOG_PROF_STRINGID2_SPAN_ID;
+
+/**
+ * A StringId that represents the string "thread id".
+ * This is always available in every string set and can be used without
+ * needing to insert it into a string set.
+ */
+extern LIBDD_DLLIMPORT const ddog_prof_StringId2 DDOG_PROF_STRINGID2_THREAD_ID;
+
+/**
+ * A StringId that represents the string "thread name".
+ * This is always available in every string set and can be used without
+ * needing to insert it into a string set.
+ */
+extern LIBDD_DLLIMPORT const ddog_prof_StringId2 DDOG_PROF_STRINGID2_THREAD_NAME;
+
+DDOG_CHECK_RETURN struct ddog_prof_Exporter_Slice_File ddog_prof_Exporter_Slice_File_empty(void);
+
+/**
+ * Creates an endpoint that uses the agent.
+ * # Arguments
+ * * `base_url` - Contains a URL with scheme, host, and port e.g. "https://agent:8126/".
+ * * `timeout_ms` - Timeout in milliseconds. Use 0 for default timeout (3000ms).
+ * * `use_system_resolver` - If true, use the system DNS resolver (less fork-safe). If false, the
+ *   default in-process resolver is used (fork-safe).
+ */
+struct ddog_prof_Endpoint ddog_prof_Endpoint_agent(ddog_CharSlice base_url,
+                                                   uint64_t timeout_ms,
+                                                   bool use_system_resolver);
+
+/**
+ * Creates an endpoint that uses the Datadog intake directly aka agentless.
+ * # Arguments
+ * * `site` - Contains a host and port e.g. "datadoghq.com".
+ * * `api_key` - Contains the Datadog API key.
+ * * `timeout_ms` - Timeout in milliseconds. Use 0 for default timeout (3000ms).
+ * * `use_system_resolver` - If true, use the system DNS resolver (less fork-safe). If false, the
+ *   default in-process resolver is used (fork-safe).
+ */
+struct ddog_prof_Endpoint ddog_prof_Endpoint_agentless(ddog_CharSlice site,
+                                                       ddog_CharSlice api_key,
+                                                       uint64_t timeout_ms,
+                                                       bool use_system_resolver);
+
+/**
+ * Creates an endpoint that writes to a file.
+ * Useful for local debugging.
+ * Currently only supported by the crashtracker.
+ * # Arguments
+ * * `filename` - Path to the output file "/tmp/file.txt".
+ */
+struct ddog_prof_Endpoint ddog_Endpoint_file(ddog_CharSlice filename);
+
+/**
+ * Creates a new exporter to be used to report profiling data.
+ * # Arguments
+ * * `profiling_library_name` - Profiling library name, usually dd-trace-something, e.g.
+ *   "dd-trace-rb". See
+ *   https://datadoghq.atlassian.net/wiki/spaces/PROF/pages/1538884229/Client#Header-values
+ *   (Datadog internal link)
+ *   for a list of common values.
+ * * `profliling_library_version` - Version used when publishing the profiling library to a package
+ *   manager
+ * * `family` - Profile family, e.g. "ruby"
+ * * `tags` - Tags to include with every profile reported by this exporter. It's also possible to
+ *   include profile-specific tags, see `additional_tags` on `profile_exporter_build`.
+ * * `endpoint` - Configuration for reporting data (includes use_system_resolver for
+ *   Agent/Agentless).
+ * # Safety
+ * All pointers must refer to valid objects of the correct types.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_ProfileExporter_Result ddog_prof_Exporter_new(ddog_CharSlice profiling_library_name,
+                                                               ddog_CharSlice profiling_library_version,
+                                                               ddog_CharSlice family,
+                                                               const struct ddog_Vec_Tag *tags,
+                                                               struct ddog_prof_Endpoint endpoint);
+
+/**
+ * # Safety
+ * The `exporter` may be null, but if non-null the pointer must point to a
+ * valid `ddog_prof_Exporter_Request` object made by the Rust Global
+ * allocator that has not already been dropped.
+ */
+void ddog_prof_Exporter_drop(struct ddog_prof_ProfileExporter *exporter);
+
+/**
+ * Initializes the tokio runtime for the exporter.
+ *
+ * This function creates the tokio runtime used by `ddog_prof_Exporter_send_blocking`.
+ * It can be called ahead of time to ensure the runtime is ready before sending.
+ *
+ * # Thread Affinity
+ *
+ * **Important**: The runtime has thread affinity. This function should be called from
+ * the same thread that will later call `ddog_prof_Exporter_send_blocking`.
+ *
+ * # Arguments
+ * * `exporter` - Borrows the exporter.
+ *
+ * # Safety
+ * The `exporter` must point to a valid ProfileExporter that has not been dropped.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_Exporter_init_runtime(struct ddog_prof_ProfileExporter *exporter);
+
+/**
+ * Builds a request and sends it, returning the HttpStatus.
+ *
+ * Note: If the runtime has not been initialized via `ddog_prof_Exporter_init_runtime`,
+ * it will be lazily initialized on first call.
+ *
+ * # Arguments
+ * * `exporter` - Borrows the exporter.
+ * * `profile` - Takes ownership of the profile.
+ * * `files_to_compress_and_export` - Files to compress and attach to the profile.
+ * * `optional_additional_tags` - Additional tags to include with this profile.
+ * * `optional_process_tags` - Process-level tags as a comma-separated string.
+ * * `optional_internal_metadata_json` - Internal metadata as a JSON string.
+ * * `optional_info_json` - System info as a JSON string.
+ * * `cancel` - Optional cancellation token.
+ *
+ * # Safety
+ * All non-null arguments MUST have been created by APIs in this module.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Result_HttpStatus ddog_prof_Exporter_send_blocking(struct ddog_prof_ProfileExporter *exporter,
+                                                                    struct ddog_prof_EncodedProfile *profile,
+                                                                    struct ddog_prof_Exporter_Slice_File files_to_compress_and_export,
+                                                                    const struct ddog_Vec_Tag *optional_additional_tags,
+                                                                    const ddog_CharSlice *optional_process_tags,
+                                                                    const ddog_CharSlice *optional_internal_metadata_json,
+                                                                    const ddog_CharSlice *optional_info_json,
+                                                                    struct ddog_CancellationToken *cancel);
+
+/**
+ * Can be passed as an argument to send and then be used to asynchronously cancel it from a
+ * different thread.
+ */
+DDOG_CHECK_RETURN struct ddog_CancellationToken ddog_CancellationToken_new(void);
+
+/**
+ * A cloned TokioCancellationToken is connected to the TokioCancellationToken it was created from.
+ * Either the cloned or the original token can be used to cancel or provided as arguments to send.
+ * The useful part is that they have independent lifetimes and can be dropped separately.
+ *
+ * Thus, it's possible to do something like:
+ * ```c
+ * cancel_t1 = ddog_CancellationToken_new();
+ * cancel_t2 = ddog_CancellationToken_clone(cancel_t1);
+ *
+ * // On thread t1:
+ *     ddog_prof_Exporter_send(..., cancel_t1);
+ *     ddog_CancellationToken_drop(cancel_t1);
+ *
+ * // On thread t2:
+ *     ddog_CancellationToken_cancel(cancel_t2);
+ *     ddog_CancellationToken_drop(cancel_t2);
+ * ```
+ *
+ * Without clone, both t1 and t2 would need to synchronize to make sure neither was using the
+ * cancel before it could be dropped. With clone, there is no need for such synchronization, both
+ * threads have their own cancel and should drop that cancel after they are done with it.
+ *
+ * # Safety
+ * If the `token` is non-null, it must point to a valid object.
+ */
+DDOG_CHECK_RETURN
+struct ddog_CancellationToken ddog_CancellationToken_clone(struct ddog_CancellationToken *token);
+
+/**
+ * Cancel send that is being called in another thread with the given token.
+ * Note that cancellation is a terminal state; cancelling a token more than once does nothing.
+ * Returns `true` if token was successfully cancelled.
+ */
+bool ddog_CancellationToken_cancel(struct ddog_CancellationToken *cancel);
+
+/**
+ * # Safety
+ * The `token` can be null, but non-null values must be created by the Rust
+ * Global allocator and must have not been dropped already.
+ */
+void ddog_CancellationToken_drop(struct ddog_CancellationToken *token);
+
+/**
+ * Creates a new ExporterManager with a background worker thread.
+ *
+ * The ExporterManager provides asynchronous profle export capabilities through a
+ * background worker thread and bounded channel.
+ *
+ * # Arguments
+ * * `exporter` - Takes ownership of the ProfileExporter to use for sending profiles.
+ *
+ * # Safety
+ * The `exporter` must point to a valid ProfileExporter that has not been dropped.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Result_HandleExporterManager ddog_prof_ExporterManager_new(struct ddog_prof_ProfileExporter *exporter);
+
+/**
+ * Queues a profile to be sent asynchronously by the background worker thread.
+ *
+ * **Important**: This function resets the profile and queues the *previous* profile data.
+ * After calling this, the profile will be empty and ready for new samples.
+ *
+ * # Arguments
+ * * `manager` - Borrows the ExporterManager.
+ * * `profile` - Takes ownership of the profile to send.
+ * * `files_to_compress_and_export` - Files to compress and attach to the profile.
+ * * `optional_additional_tags` - Additional tags to include with this profile.
+ * * `optional_process_tags` - Process-level tags as a comma-separated string.
+ * * `optional_internal_metadata_json` - Internal metadata as a JSON string.
+ * * `optional_info_json` - System info as a JSON string.
+ *
+ * # Safety
+ * All non-null arguments MUST have been created by APIs in this module.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_ExporterManager_queue(struct ddog_prof_Handle_ExporterManager *manager,
+                                                       struct ddog_prof_EncodedProfile *profile,
+                                                       struct ddog_prof_Exporter_Slice_File files_to_compress_and_export,
+                                                       const struct ddog_Vec_Tag *optional_additional_tags,
+                                                       const ddog_CharSlice *optional_process_tags,
+                                                       const ddog_CharSlice *optional_internal_metadata_json,
+                                                       const ddog_CharSlice *optional_info_json);
+
+/**
+ * Aborts the manager, stopping the worker thread and returning inflight requests.
+ *
+ * **Note**: This consumes the manager - it cannot be used after calling abort.
+ *
+ * # Arguments
+ * * `manager` - Takes ownership of the ExporterManager.
+ *
+ * # Safety
+ * The `manager` must point to a valid ExporterManager that has not been dropped.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_ExporterManager_abort(struct ddog_prof_Handle_ExporterManager *manager);
+
+/**
+ * Suspends the manager before forking (prefork).
+ *
+ * **Note**: This consumes the manager - it cannot be used after calling prefork.
+ *
+ * # Arguments
+ * * `manager` - Takes ownership of the ExporterManager.
+ *
+ * # Safety
+ * The `manager` must point to a valid ExporterManager that has not been dropped.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_ExporterManager_prefork(struct ddog_prof_Handle_ExporterManager *manager);
+
+/**
+ * Creates a new manager in the child process after forking (postfork_child).
+ *
+ * Inflight requests from the parent are discarded in the child.
+ *
+ * # Arguments
+ * * `suspended` - Takes ownership of the suspended ExporterManager.
+ *
+ * # Safety
+ * The `suspended` must point to a valid suspended ExporterManager that has not been dropped.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_ExporterManager_postfork_child(struct ddog_prof_Handle_ExporterManager *suspended);
+
+/**
+ * Creates a new manager in the parent process after forking (postfork_parent).
+ *
+ * Inflight requests from before the fork are re-queued in the new manager.
+ *
+ * # Arguments
+ * * `suspended` - Takes ownership of the suspended ExporterManager.
+ *
+ * # Safety
+ * The `suspended` must point to a valid suspended ExporterManager that has not been dropped.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_ExporterManager_postfork_parent(struct ddog_prof_Handle_ExporterManager *suspended);
+
+/**
+ * # Safety
+ * The `manager` may be null, but if non-null the pointer must point to a
+ * valid `ExporterManager` object made by the Rust Global allocator that
+ * has not already been dropped.
+ */
+void ddog_prof_ExporterManager_drop(struct ddog_prof_Handle_ExporterManager *manager);
+
+/**
+ * Frees any error associated with the status, and replaces it with an OK.
+ *
+ * # Safety
+ *
+ * The pointer should point at a valid Status object, if it's not null.
+ */
+void ddog_prof_Status_drop(struct ddog_prof_Status *status);
+
+/**
+ * Create a new profile with the given sample types. Must call
+ * `ddog_prof_Profile_drop` when you are done with the profile.
+ *
+ * # Arguments
+ * * `sample_types` - A slice of SampleType enums
+ * * `period` - Optional period of the profile. Passing None/null translates to zero values.
+ * * `start_time` - Optional time the profile started at. Passing None/null will use the current
+ *   time.
+ *
+ * # Safety
+ * All slices must be have pointers that are suitably aligned for their type
+ * and must have the correct number of elements for the slice.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_NewResult ddog_prof_Profile_new(struct ddog_prof_Slice_SampleType sample_types,
+                                                         const struct ddog_prof_Period *period);
+
+/**
+ * Create a new profile with the given sample types. Must call
+ * `ddog_prof_Profile_drop` when you are done with the profile.
+ *
+ * # Arguments
+ * * `out` - a non-null pointer to an uninitialized Profile.
+ * * `dict`: a valid reference to a ProfilesDictionary handle.
+ * * `sample_types` - A slice of SampleType enums
+ * * `period` - Optional period of the profile. Passing None/null translates to zero values.
+ *
+ * # Safety
+ * All slices must have pointers that are suitably aligned for their type
+ * and must have the correct number of elements for the slice.
+ *
+ * The `dict` reference must be to a valid ProfilesDictionary handle. It may
+ * be an empty handle, but it must be a valid handle.
+ *
+ * The `out` pointer must be non-null and suitable for pointer writes,
+ * including that it has the correct size and alignment.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Status ddog_prof_Profile_with_dictionary(struct ddog_prof_Profile *out,
+                                                          const ddog_prof_ProfilesDictionaryHandle *dict,
+                                                          struct ddog_prof_Slice_SampleType sample_types,
+                                                          const struct ddog_prof_Period *period);
+
+/**
+ * Same as `ddog_profile_new` but also configures a `string_storage` for the profile.
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_NewResult ddog_prof_Profile_with_string_storage(struct ddog_prof_Slice_SampleType sample_types,
+                                                                         const struct ddog_prof_Period *period,
+                                                                         struct ddog_prof_ManagedStringStorage string_storage);
+
+/**
+ * # Safety
+ * The `profile` can be null, but if non-null it must point to a Profile
+ * made by this module, which has not previously been dropped.
+ */
+void ddog_prof_Profile_drop(struct ddog_prof_Profile *profile);
+
+/**
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module. All pointers inside the `sample` need to be valid for the duration
+ * of this call.
+ *
+ * If successful, it returns the Ok variant.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_Result ddog_prof_Profile_add(struct ddog_prof_Profile *profile,
+                                                      struct ddog_prof_Sample sample,
+                                                      int64_t timestamp);
+
+/**
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module. All pointers inside the `sample` need to be valid for the duration
+ * of this call.
+ *
+ * If successful, it returns the Ok variant.
+ * On error, it holds an error message in the error variant.
+ *
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Status ddog_prof_Profile_add2(struct ddog_prof_Profile *profile,
+                                               struct ddog_prof_Sample2 sample,
+                                               int64_t timestamp);
+
+/**
+ * Associate an endpoint to a given local root span id.
+ * During the serialization of the profile, an endpoint label will be added
+ * to all samples that contain a matching local root span id label.
+ *
+ * Note: calling this API causes the "trace endpoint" and "local root span id" strings
+ * to be interned, even if no matching sample is found.
+ *
+ * # Arguments
+ * * `profile` - a reference to the profile that will contain the samples.
+ * * `local_root_span_id`
+ * * `endpoint` - the value of the endpoint label to add for matching samples.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_Result ddog_prof_Profile_set_endpoint(struct ddog_prof_Profile *profile,
+                                                               uint64_t local_root_span_id,
+                                                               ddog_CharSlice endpoint);
+
+/**
+ * Count the number of times an endpoint has been seen.
+ *
+ * # Arguments
+ * * `profile` - a reference to the profile that will contain the samples.
+ * * `endpoint` - the endpoint label for which the count will be incremented
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_Result ddog_prof_Profile_add_endpoint_count(struct ddog_prof_Profile *profile,
+                                                                     ddog_CharSlice endpoint,
+                                                                     int64_t value);
+
+/**
+ * Add a poisson-based upscaling rule which will be use to adjust values and make them
+ * closer to reality.
+ *
+ * # Arguments
+ * * `profile` - a reference to the profile that will contain the samples.
+ * * `offset_values` - offset of the values
+ * * `label_name` - name of the label used to identify sample(s)
+ * * `label_value` - value of the label used to identify sample(s)
+ * * `sum_value_offset` - offset of the value used as a sum (compute the average with
+ *   `count_value_offset`)
+ * * `count_value_offset` - offset of the value used as a count (compute the average with
+ *   `sum_value_offset`)
+ * * `sampling_distance` - this is the threshold for this sampling window. This value must not be
+ *   equal to 0
+ *
+ * # Safety
+ * This function must be called before serialize and must not be called after.
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_Result ddog_prof_Profile_add_upscaling_rule_poisson(struct ddog_prof_Profile *profile,
+                                                                             struct ddog_prof_Slice_Usize offset_values,
+                                                                             ddog_CharSlice label_name,
+                                                                             ddog_CharSlice label_value,
+                                                                             uintptr_t sum_value_offset,
+                                                                             uintptr_t count_value_offset,
+                                                                             uint64_t sampling_distance);
+
+/**
+ * Add a proportional-based upscaling rule which will be use to adjust values and make them
+ * closer to reality.
+ *
+ * # Arguments
+ * * `profile` - a reference to the profile that will contain the samples.
+ * * `offset_values` - offset of the values
+ * * `label_name` - name of the label used to identify sample(s)
+ * * `label_value` - value of the label used to identify sample(s)
+ * * `total_sampled` - number of sampled event (found in the pprof). This value must not be equal
+ *   to 0
+ * * `total_real` - number of events the profiler actually witnessed. This value must not be equal
+ *   to 0
+ *
+ * # Safety
+ * This function must be called before serialize and must not be called after.
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_Result ddog_prof_Profile_add_upscaling_rule_proportional(struct ddog_prof_Profile *profile,
+                                                                                  struct ddog_prof_Slice_Usize offset_values,
+                                                                                  ddog_CharSlice label_name,
+                                                                                  ddog_CharSlice label_value,
+                                                                                  uint64_t total_sampled,
+                                                                                  uint64_t total_real);
+
+/**
+ * # Safety
+ * Only pass a reference to a valid `ddog_prof_EncodedProfile`, or null. A
+ * valid reference also means that it hasn't already been dropped or exported (do not
+ * call this twice on the same object).
+ */
+void ddog_prof_EncodedProfile_drop(struct ddog_prof_EncodedProfile *profile);
+
+/**
+ * Given an EncodedProfile, get a slice representing the bytes in the pprof.
+ * This slice is valid for use until the encoded_profile is modified in any way (e.g. dropped or
+ * consumed).
+ * # Safety
+ * Only pass a reference to a valid `ddog_prof_EncodedProfile`.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Result_ByteSlice ddog_prof_EncodedProfile_bytes(struct ddog_prof_EncodedProfile *encoded_profile);
+
+/**
+ * Serialize the aggregated profile.
+ * Drains the data, and then resets the profile for future use.
+ *
+ * Don't forget to clean up the ok with `ddog_prof_EncodedProfile_drop` or
+ * the error variant with `ddog_Error_drop` when you are done with them.
+ *
+ * # Arguments
+ * * `profile` - a reference to the profile being serialized.
+ * * `start_time` - optional start time for the serialized profile. If None/null is passed, the
+ *   time of profile creation will be used.
+ * * `end_time` - optional end time of the profile. If None/null is passed, the current time will
+ *   be used.
+ *
+ * # Safety
+ * The `profile` must point to a valid profile object.
+ * The `start_time` and `end_time` must be null or otherwise point to a valid TimeSpec object.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_SerializeResult ddog_prof_Profile_serialize(struct ddog_prof_Profile *profile,
+                                                                     const struct ddog_Timespec *start_time,
+                                                                     const struct ddog_Timespec *end_time);
+
+DDOG_CHECK_RETURN struct ddog_Slice_U8 ddog_Vec_U8_as_slice(const struct ddog_Vec_U8 *vec);
+
+/**
+ * Resets all data in `profile` except the sample types and period. Returns
+ * true if it successfully reset the profile and false otherwise. The profile
+ * remains valid if false is returned.
+ *
+ * # Arguments
+ * * `profile` - A mutable reference to the profile to be reset.
+ * * `start_time` - The time of the profile (after reset). Pass None/null to use the current time.
+ *
+ * # Safety
+ * The `profile` must meet all the requirements of a mutable reference to the profile. Given this
+ * can be called across an FFI boundary, the compiler cannot enforce this.
+ * If `time` is not null, it must point to a valid Timespec object.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Profile_Result ddog_prof_Profile_reset(struct ddog_prof_Profile *profile);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_FunctionId_Result ddog_prof_Profile_intern_function(struct ddog_prof_Profile *profile,
+                                                                     struct ddog_prof_StringId name,
+                                                                     struct ddog_prof_StringId system_name,
+                                                                     struct ddog_prof_StringId filename);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_LabelId_Result ddog_prof_Profile_intern_label_num(struct ddog_prof_Profile *profile,
+                                                                   struct ddog_prof_StringId key,
+                                                                   int64_t val);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_LabelId_Result ddog_prof_Profile_intern_label_num_with_unit(struct ddog_prof_Profile *profile,
+                                                                             struct ddog_prof_StringId key,
+                                                                             int64_t val,
+                                                                             struct ddog_prof_StringId unit);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_LabelId_Result ddog_prof_Profile_intern_label_str(struct ddog_prof_Profile *profile,
+                                                                   struct ddog_prof_StringId key,
+                                                                   struct ddog_prof_StringId val);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_LabelSetId_Result ddog_prof_Profile_intern_labelset(struct ddog_prof_Profile *profile,
+                                                                     struct ddog_prof_Slice_LabelId labels);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_LocationId_Result ddog_prof_Profile_intern_location(struct ddog_prof_Profile *profile,
+                                                                     struct ddog_prof_FunctionId function_id,
+                                                                     uint64_t address,
+                                                                     int64_t line);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_LocationId_Result ddog_prof_Profile_intern_location_with_mapping_id(struct ddog_prof_Profile *profile,
+                                                                                     struct ddog_prof_MappingId mapping_id,
+                                                                                     struct ddog_prof_FunctionId function_id,
+                                                                                     uint64_t address,
+                                                                                     int64_t line);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_StringId_Result ddog_prof_Profile_intern_managed_string(struct ddog_prof_Profile *profile,
+                                                                         struct ddog_prof_ManagedStringId s);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_Profile_intern_managed_strings(struct ddog_prof_Profile *profile,
+                                                                struct ddog_prof_Slice_ManagedStringId strings,
+                                                                struct ddog_prof_MutSlice_GenerationalIdStringId out);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_MappingId_Result ddog_prof_Profile_intern_mapping(struct ddog_prof_Profile *profile,
+                                                                   uint64_t memory_start,
+                                                                   uint64_t memory_limit,
+                                                                   uint64_t file_offset,
+                                                                   struct ddog_prof_StringId filename,
+                                                                   struct ddog_prof_StringId build_id);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns void.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_Profile_intern_sample(struct ddog_prof_Profile *profile,
+                                                       struct ddog_prof_StackTraceId stacktrace,
+                                                       struct ddog_Slice_I64 values,
+                                                       struct ddog_prof_LabelSetId labels,
+                                                       int64_t timestamp);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_StackTraceId_Result ddog_prof_Profile_intern_stacktrace(struct ddog_prof_Profile *profile,
+                                                                         struct ddog_prof_Slice_LocationId locations);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_StringId_Result ddog_prof_Profile_intern_string(struct ddog_prof_Profile *profile,
+                                                                 ddog_CharSlice s);
+
+/**
+ * This functions returns an interned id for an empty string
+ *
+ * # Safety
+ * No preconditions
+ */
+struct ddog_prof_StringId ddog_prof_Profile_interned_empty_string(void);
+
+/**
+ * This function interns its argument into the profiler.
+ * If successful, it returns an opaque interning ID.
+ * This ID is valid for use on this profiler, until the profiler is reset.
+ * It is an error to use this id after the profiler has been reset, or on a different profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * All other arguments must remain valid for the length of this call.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_Profile_intern_strings(struct ddog_prof_Profile *profile,
+                                                        struct ddog_prof_Slice_CharSlice strings,
+                                                        struct ddog_prof_MutSlice_GenerationalIdStringId out);
+
+/**
+ * This functions returns the current generation of the profiler.
+ * On error, it holds an error message in the error variant.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is _NOT_ thread-safe.
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_Result_Generation ddog_prof_Profile_get_generation(struct ddog_prof_Profile *profile);
+
+/**
+ * This functions returns whether the given generations are equal.
+ *
+ * # Safety: No safety requirements
+ */
+DDOG_CHECK_RETURN
+bool ddog_prof_Profile_generations_are_equal(struct ddog_prof_Generation a,
+                                             struct ddog_prof_Generation b);
+
+/**
+ * This functions ends the current sample and allows the profiler exporter to continue, if it was
+ * blocked.
+ * It must have been paired with exactly one `sample_start`.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is probably thread-safe, but I haven't confirmed this.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_Profile_sample_end(struct ddog_prof_Profile *profile);
+
+/**
+ * This functions starts a sample and blocks the exporter from continuing.
+ *
+ * # Safety
+ * The `profile` ptr must point to a valid Profile object created by this
+ * module.
+ * This call is probably thread-safe, but I haven't confirmed this.
+ */
+DDOG_CHECK_RETURN
+struct ddog_VoidResult ddog_prof_Profile_sample_start(struct ddog_prof_Profile *profile);
+
+/**
+ * Allocates a new `ProfilesDictionary` and writes a handle to it in `handle`.
+ *
+ * # Safety
+ *
+ * - `handle` must be non-null and valid for writes of `ProfilesDictionaryHandle`.
+ * - The returned handle must eventually drop the resource; see
+ *   [`ddog_prof_ProfilesDictionary_drop`] for more details.
+ * - If you need a copy, use [`ddog_prof_ProfilesDictionary_try_clone`]; don't just memcpy a new
+ *   handle.
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_new(ddog_prof_ProfilesDictionaryHandle *handle);
+
+/**
+ * Creates a new handle to the same `ProfilesDictionary` by incrementing the
+ * internal reference count.
+ *
+ * # Safety
+ *
+ * - `out` must be non-null and valid for writes of `ProfilesDictionaryHandle`.
+ * - `handle` must point to a live dictionary resource.
+ * - Do not duplicate handles via memcpy; always use this API to create new handles so the
+ *   reference count is maintained correctly.
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_try_clone(ddog_prof_ProfilesDictionaryHandle *out,
+                                                               ddog_prof_ProfilesDictionaryHandle handle);
+
+/**
+ * Inserts a `Function` into the dictionary and returns its id.
+ *
+ * # Safety
+ *
+ * - `function_id` must be non-null and valid for writes of `FunctionId`.
+ * - `dict` must refer to a live dictionary.
+ * - `function` must be non-null and point to a valid `Function` for the duration of the call.
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_insert_function(ddog_prof_FunctionId2 *function_id,
+                                                                     const struct ddog_prof_ProfilesDictionary *dict,
+                                                                     const struct ddog_prof_Function2 *function);
+
+/**
+ * Inserts a `Mapping` into the dictionary and returns its id.
+ *
+ * # Safety
+ *
+ * - `mapping_id` must be non-null and valid for writes of `MappingId`.
+ * - `dict` must refer to a live dictionary.
+ * - `mapping` must be non-null and point to a valid `Mapping` for the duration of the call.
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_insert_mapping(ddog_prof_MappingId2 *mapping_id,
+                                                                    const struct ddog_prof_ProfilesDictionary *dict,
+                                                                    const struct ddog_prof_Mapping2 *mapping);
+
+/**
+ * Inserts a UTF-8 string into the dictionary string table.
+ *
+ * Copies the string into the internal buffer--strings are arena allocated
+ * and not individually allocated. On success, the [`StringId2`] written to
+ * the `string_id` out parameter is valid as long as this dictionary is alive.
+ * It should only be passed back to the dictionary that created it.
+ *
+ * # Safety
+ *
+ * - `string_id` must be non-null and valid for writes of `StringId`.
+ * - `handle` must refer to a live dictionary.
+ * - The UTF-8 policy indicated by `utf8_option` must be respected by caller for the provided
+ *   `byte_slice`.
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_insert_str(ddog_prof_StringId2 *string_id,
+                                                                const struct ddog_prof_ProfilesDictionary *dict,
+                                                                ddog_CharSlice byte_slice,
+                                                                enum ddog_prof_Utf8Option utf8_option);
+
+/**
+ * Inserts a batch of UTF-8 strings into the dictionary string table.
+ *
+ * On success, each element of `string_ids` corresponds to the same-index element of
+ * `strings`. The length of `string_ids` must equal the length of `strings`; a
+ * mismatch is an error.
+ *
+ * On failure the number of entries written to `string_ids` is unspecified; callers
+ * must not read any element of `string_ids`.
+ *
+ * # Safety
+ *
+ * - `dict` must refer to a live dictionary.
+ * - `strings` must be a valid slice for the duration of the call.
+ * - `string_ids` must be a valid writable slice of `StringId2` with the same length as `strings`.
+ * - The UTF-8 policy indicated by `utf8_option` must be respected by the caller for every string
+ *   in `strings`.
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_insert_strs(struct ddog_prof_MutSlice_StringId2 string_ids,
+                                                                 const struct ddog_prof_ProfilesDictionary *dict,
+                                                                 struct ddog_prof_Slice_CharSlice strings,
+                                                                 enum ddog_prof_Utf8Option utf8_option);
+
+/**
+ * Tries to get the string value associated with the string id. Fails if the
+ * handle has been taken from, or the result param is null.
+ *
+ * # Safety
+ *
+ *  1. The lifetime of the return slice is tied to the underlying storage of the string set, make
+ *     sure the string set is still alive when using the returned slice.
+ *  2. The string id should belong to the string set in this dictionary. Well-known strings are an
+ *     exception, as they exist in every set.
+ *  3. The handle must represent a live profiles dictionary. Remember handles can be copied, and if
+ *     _any_ handle drops the resource, then all handles pointing the resource are now invalid,
+ *     even if though they are unaware of it.
+ *  4. The result pointer must valid for [`core::ptr::write`].
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_get_str(ddog_CharSlice *result,
+                                                             const struct ddog_prof_ProfilesDictionary *dict,
+                                                             ddog_prof_StringId2 string_id);
+
+/**
+ * Tries to get the function value associated with the function id.
+ *
+ * # Safety
+ *
+ *  1. The `function_id` should belong to this dictionary.
+ *  2. The dictionary must be live for the duration of the call.
+ *  3. The result pointer must be valid for [`core::ptr::write`].
+ */
+struct ddog_prof_Status ddog_prof_ProfilesDictionary_get_func(struct ddog_prof_Function2 *result,
+                                                              const struct ddog_prof_ProfilesDictionary *dict,
+                                                              ddog_prof_FunctionId2 function_id);
+
+/**
+ * Drops the `ProfilesDictionary` that the handle owns, leaving a valid but
+ * useless handle (all operations on it will error). This takes a pointer to
+ * the handle to be able to modify it to leave behind an empty handle.
+ *
+ * # Safety
+ *
+ * - If non-null, `handle` must point to a valid `ProfilesDictionaryHandle`.
+ * - The underlying resource must be dropped exactly once across all copies of the handle. After
+ *   dropping, all other copies become invalid and must not be used; they should be discarded
+ *   without dropping.
+ */
+void ddog_prof_ProfilesDictionary_drop(ddog_prof_ProfilesDictionaryHandle *handle);
+
+DDOG_CHECK_RETURN
+struct ddog_prof_ManagedStringStorageNewResult ddog_prof_ManagedStringStorage_new(void);
+
+/**
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+void ddog_prof_ManagedStringStorage_drop(struct ddog_prof_ManagedStringStorage storage);
+
+/**
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+DDOG_CHECK_RETURN
+struct ddog_prof_ManagedStringStorageInternResult ddog_prof_ManagedStringStorage_intern(struct ddog_prof_ManagedStringStorage storage,
+                                                                                        ddog_CharSlice string);
+
+/**
+ * Interns all the strings in `strings`, writing the resulting id to the same
+ * offset in `output_ids`.
+ *
+ * This can fail if:
+ *  1. The given `output_ids_size` doesn't match the size of the input slice.
+ *  2. The internal storage pointer is null.
+ *  3. It fails to acquire a lock (e.g. it was poisoned).
+ *  4. Defensive checks against bugs fail.
+ *
+ * If a failure occurs, do not use any of the ids in the output array. After
+ * this point, you should only use read-only routines (except for drop) on
+ * the managed string storage.
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+ddog_prof_MaybeError ddog_prof_ManagedStringStorage_intern_all(struct ddog_prof_ManagedStringStorage storage,
+                                                               struct ddog_prof_Slice_CharSlice strings,
+                                                               struct ddog_prof_ManagedStringId *output_ids,
+                                                               uintptr_t output_ids_size);
+
+/**
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+ddog_prof_MaybeError ddog_prof_ManagedStringStorage_unintern(struct ddog_prof_ManagedStringStorage storage,
+                                                             struct ddog_prof_ManagedStringId id);
+
+/**
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+ddog_prof_MaybeError ddog_prof_ManagedStringStorage_unintern_all(struct ddog_prof_ManagedStringStorage storage,
+                                                                 struct ddog_prof_Slice_ManagedStringId ids);
+
+/**
+ * Returns a string given its id.
+ * This API is mostly for testing, overall you should avoid reading back strings from libdatadog
+ * once they've been interned and should instead always operate on the id.
+ * Remember to `ddog_StringWrapper_drop` the string once you're done with it.
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+DDOG_CHECK_RETURN
+struct ddog_StringWrapperResult ddog_prof_ManagedStringStorage_get_string(struct ddog_prof_ManagedStringStorage storage,
+                                                                          struct ddog_prof_ManagedStringId id);
+
+/**
+ * TODO: @ivoanjo Should this take a `*mut ManagedStringStorage` like Profile APIs do?
+ */
+ddog_prof_MaybeError ddog_prof_ManagedStringStorage_advance_gen(struct ddog_prof_ManagedStringStorage storage);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif  // __cplusplus
+
+#endif  /* DDOG_PROFILING_H */