@ogcio/o11y-sdk-node/dist/sdk-core/lib/utils/geo-context.d.ts

Opentelemetry standard instrumentation SDK for NodeJS based project

import { type Context, type TextMapGetter } from "@opentelemetry/api";
export declare const geoBaggageKeys: readonly ["geo.country", "geo.city", "geo.hash"];
type GeoKey = (typeof geoBaggageKeys)[number];
export type GeoAttributes = Partial<Record<GeoKey, string>>;
export type GeoInput = {
    lat?: number;
    lon?: number;
    country?: string;
    city?: string;
    precision?: number;
};
/**
 * Maps geo fields to the header names that carry them.
 * `CF_GEO_HEADERS` is the CloudFront default; other providers can supply their own.
 */
export interface GeoHeaderMap {
    COUNTRY: string;
    CITY: string;
    LATITUDE: string;
    LONGITUDE: string;
}
/**
 * CloudFront viewer header names carrying geo information.
 * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html
 */
export declare const CF_GEO_HEADERS: {
    readonly COUNTRY: "cloudfront-viewer-country";
    readonly CITY: "cloudfront-viewer-city";
    readonly LATITUDE: "cloudfront-viewer-latitude";
    readonly LONGITUDE: "cloudfront-viewer-longitude";
};
/** A plain header carrier map as read by `defaultTextMapGetter` (e.g. Node's `IncomingHttpHeaders`). */
export type HeaderCarrier = Record<string, string | string[] | undefined>;
/** Reads a single header value, collapsing multi-valued headers to their first entry. */
export declare function getHeaderValue<Carrier = HeaderCarrier>(carrier: Carrier, key: string, getter?: TextMapGetter<Carrier>): string | undefined;
/**
 * Returns geo attributes from the given OTel context's baggage.
 * Use this in span and log processors where the context is passed explicitly.
 */
export declare function getGeoAttributesFromContext(ctx: Context): GeoAttributes;
/**
 * Returns geo attributes for the current request context.
 * Reads from OTel Baggage on the active context, set by GeoBaggagePropagator.
 * Use this to manually enrich custom spans, logs, or metrics when geo-enrichment is enabled.
 */
export declare function getGeoAttributes(): GeoAttributes;
/**
 * Builds geo attributes from any combination of geo inputs.
 * A geohash is computed automatically when both `lat` and `lon` are provided.
 * Use this to create geo attributes to attach to signals when auto-enrichment is not enabled.
 */
export declare function createGeoAttributesFrom(input: GeoInput): GeoAttributes;
/** Options for {@link createGeoAttributesFromHeaders}. */
export interface GeoHeadersOptions<Carrier = HeaderCarrier> {
    /** Getter used to read the carrier. Defaults to `defaultTextMapGetter`. */
    getter?: TextMapGetter<Carrier>;
    /** Geohash precision. */
    precision?: number;
    /** Header name mapping. Defaults to `CF_GEO_HEADERS`. */
    headerMap?: GeoHeaderMap;
}
/**
 * Builds geo attributes directly from provider headers.
 * Use this to enrich a single span, log, or metric when auto-enrichment is not enabled.
 */
export declare function createGeoAttributesFromHeaders<Carrier = HeaderCarrier>(carrier: Carrier, options?: GeoHeadersOptions<Carrier>): GeoAttributes;
export {};