@opentelemetry/core/dist/common/attributes.d.mts

OpenTelemetry Core provides constants and utilities shared by all OpenTelemetry SDK packages.

import { AnyValue, Attributes } from "@opentelemetry/api";
//#region src/common/attributes.d.ts
/**
 * A simpler attribute value with limited supported types.
 * This is the set of types that `Attributes` supported in versions of
 * `@opentelemetry/api` before v1.10.0.
 */
type SimpleAttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
declare enum AddAttributeDecision {
  DROP_UNDEFINED = 0,
  DROP_INVALID = 1,
  DROP_LIMIT_REACHED = 2,
  ADD_NEW = 3,
  ADD_OVERWRITE_EXISTING = 4
}
type AttributeLimits = {
  attributeCountLimit: number;
  attributeValueLengthLimit: number;
};
type MaybeAddAttributeOpts = {
  key: string;
  value: AnyValue;
  attributes: Attributes;
  limits: AttributeLimits;
  currentAttributesCount: number;
};
/**
 * Maybe add the `key`/`val` attribute to the given `attributes`.
 * - "Maybe" because this ensures the `key` is valid (the string is not empty),
 *   the `val` is an accepted spec AnyValue type (see `isAnyValue` below),
 *   and the attribute does not need to be dropped because of a count limit.
 *   Note that the TypeScript `AnyValue` type is *looser* than the spec
 *   `AnyValue`.
 * - This also applies attribute count and value length limits.
 * - This returns an `AddAttributeDecision` enum value indicating whether,
 *   why, and how the attribute was added. This can be relevant for the
 *   caller updating metrics (e.g. `droppedAttributesCount`).
 */
declare function maybeAddAttribute(opts: MaybeAddAttributeOpts): AddAttributeDecision;
/**
 * A version of `maybeAddAttribute` that limits allowed attribute value
 * types to "simple" types (`SimpleAttributeValue`).
 */
declare function maybeAddSimpleAttribute(opts: MaybeAddAttributeOpts): AddAttributeDecision;
/**
 * Clean a given set of attributes.
 * - `undefined` values, at the top-level and properties of nested objects,
 *   are silently dropped
 * - invalid attribute value types are removed, with a warning
 * - attribute count and value length *limits* are applied
 *
 * The call signature is meant to make it ergonomic for creating SDK things
 * that take `attributes` and `droppedAttributesCount` arguments, e.g.:
 *    this.links({
 *      context: opts.context,
 *      ...cleanAttributes(opts.attributes, attributeLimits)
 *    });
 *
 * If the given `inAttributes` is undefined, then the properties in the
 * return value will be undefined.
 */
declare function cleanAttributes(inAttributes: unknown, limits: AttributeLimits): {
  attributes?: Attributes;
  droppedAttributesCount?: number;
};
/**
 * A version of `cleanAttributes` that limits allowed attribute value types to
 * "simple" types (`SimpleAttributeValue`).
 */
declare function cleanSimpleAttributes(inAttributes: unknown, limits: AttributeLimits): {
  attributes?: Attributes;
  droppedAttributesCount?: number;
};
/**
 * Returns true iff the given value is a supported AnyValue per
 * https://opentelemetry.io/docs/specs/otel/common/#anyvalue
 *
 * - Primitives/scalars: string, boolean, number
 *   (Note that this *excludes* BigInt and Symbol)
 * - Byte arrays (Uint8Array, Buffer)
 * - Arrays of AnyValue (heterogeneous arrays allowed)
 * - Maps from string to AnyValue (nested objects)
 * - Empty values (null)
 *
 * Notes:
 * - `undefined` is *not* considered an AnyValue.
 *
 * @param val
 * @returns true if the value is a valid AnyValue, false otherwise
 */
declare function isAnyValue(val: unknown): boolean;
/**
 * Clean the given attributes to just those with "simple" attribute types.
 * This remains for backwards compatibility with 2.x.
 *
 * Changes to previous behavior:
 * - a default attribute count limit of 128 is applied
 * - nullish values (except in arrays) are removed
 *
 * @deprecated Use `cleanAttributes` or `cleanSimpleAttributes`.
 */
declare function sanitizeAttributes(inAttributes: unknown): Attributes;
/**
 * Return true if the given attribute value is a "simple" attribute value type.
 *
 * Changes to previous behavior: nullish values now return *false*.
 *
 * @deprecated use `isAnyValue`, or `isSimpleAttributeValue`.
 */
declare const isAttributeValue: typeof isSimpleAttributeValue;
declare function isSimpleAttributeValue(val: unknown): val is SimpleAttributeValue;
//#endregion
export { AddAttributeDecision, cleanAttributes, cleanSimpleAttributes, isAnyValue, isAttributeValue, isSimpleAttributeValue, maybeAddAttribute, maybeAddSimpleAttribute, sanitizeAttributes };
//# sourceMappingURL=attributes.d.mts.map