/**
 * Tier Policy Hints
 *
 * SDK-level hints that inform the OTEL Collector how to route spans.
 * These are HINTS, not guarantees — the Collector makes final routing decisions.
 *
 * NOTE: This is different from tier TAGS (which indicate which pipeline processed
 * a span). Hints are prescriptive ("please route this way"), tags are descriptive
 * ("this was processed by Tier X"). The Collector adds tier tags; the SDK adds hints.
 *
 * See: engineering/projects/o11y-refactor/proposals/sdk-tier-policy-hints.md
 */
import type { Span } from "@opentelemetry/api";
/**
 * The attribute key used for tier policy hints.
 * Collector filters on this attribute to make routing decisions.
 */
export declare const TIER_HINT_ATTRIBUTE = "superblocks.tier_hint";
/**
 * Tier policy hints that inform the Collector how to route spans.
 *
 * These are HINTS, not guarantees — the Collector makes final routing decisions
 * based on its configuration. In cloud-prem deployments, the Collector respects
 * these hints to control which tiers receive the span.
 *
 * @example
 * ```typescript
 * import { trace } from '@opentelemetry/api';
 * import { TierPolicyHint, TIER_HINT_ATTRIBUTE } from '@superblocksteam/telemetry';
 *
 * const span = tracer.startSpan('sensitive_operation');
 * span.setAttribute(TIER_HINT_ATTRIBUTE, TierPolicyHint.TIER1_ONLY);
 * ```
 */
export declare enum TierPolicyHint {
    /**
     * Route to Tier 1 only. Do not export to Tier 2 or Tier 3.
     *
     * Use for:
     * - Spans containing customer secrets or credentials
     * - Highly sensitive customer data that must not leave their environment
     * - Debug/diagnostic spans that should remain local
     *
     * The span will be stored in the customer's Tier 1 backend (e.g., Tempo)
     * but will NOT be exported to Superblocks (Tier 2) or AI analytics (Tier 3).
     */
    TIER1_ONLY = "tier1_only",
    /**
     * Include in Tier 3 (AI quality analysis) in addition to Tier 1 and Tier 2.
     *
     * Use for:
     * - GenAI spans that should be analyzed for quality metrics
     * - AI/LLM operations where prompts and responses are valuable for analysis
     * - Spans with AI quality signals (latency, token usage, etc.)
     *
     * The span will go to all tiers: Tier 1 (full fidelity), Tier 2 (sanitized),
     * and Tier 3 (AI analytics with identity stripped).
     */
    INCLUDE_TIER3 = "include_tier3",
    /**
     * Skip all external export. Tier 1 (local) only, no Tier 2/3.
     * Alias for TIER1_ONLY, kept for semantic clarity.
     *
     * Use for:
     * - High-cardinality diagnostic spans (cost control)
     * - Temporary debug spans that shouldn't persist
     * - Spans that are only useful for local debugging
     *
     * This is functionally equivalent to TIER1_ONLY but communicates
     * a different intent: "this is for cost/noise control" rather than
     * "this contains sensitive data."
     */
    SKIP_EXPORT = "skip_export"
}
/**
 * Set a tier policy hint on a span.
 *
 * This is a convenience function that sets the `superblocks.tier_hint` attribute.
 * You can also set the attribute directly if preferred.
 *
 * @param span - The span to set the hint on
 * @param hint - The tier policy hint
 *
 * @example
 * ```typescript
 * import { setTierHint, TierPolicyHint } from '@superblocksteam/telemetry';
 *
 * tracer.startActiveSpan('decrypt_secret', (span) => {
 *   setTierHint(span, TierPolicyHint.TIER1_ONLY);
 *   // ... perform operation
 *   span.end();
 * });
 * ```
 */
export declare function setTierHint(span: Span, hint: TierPolicyHint): void;
/**
 * Mark a span as containing sensitive data that should not leave Tier 1.
 *
 * Use this for spans that handle customer secrets, credentials, or other
 * highly sensitive data that must remain in the customer's environment.
 *
 * @param span - The span to mark as sensitive
 *
 * @example
 * ```typescript
 * import { markSensitive } from '@superblocksteam/telemetry';
 *
 * tracer.startActiveSpan('decrypt_customer_secret', (span) => {
 *   markSensitive(span);
 *   // ... decrypt operation
 *   span.end();
 * });
 * ```
 */
export declare function markSensitive(span: Span): void;
/**
 * Mark a span for AI quality analysis (Tier 3).
 *
 * Use this for GenAI spans that should be analyzed for quality metrics.
 * The span will go to all tiers, with Tier 3 receiving the content
 * (prompts/responses) for AI quality analysis.
 *
 * @param span - The span to mark for AI analysis
 *
 * @example
 * ```typescript
 * import { markForAIAnalysis } from '@superblocksteam/telemetry';
 *
 * tracer.startActiveSpan('gen_ai.chat', (span) => {
 *   markForAIAnalysis(span);
 *   span.setAttribute('gen_ai.system', 'anthropic');
 *   // ... LLM call
 *   span.end();
 * });
 * ```
 */
export declare function markForAIAnalysis(span: Span): void;
/**
 * Mark a span as debug-only (no export to Tier 2/3).
 *
 * Use this for high-cardinality diagnostic spans where you want to
 * control costs by preventing export to paid backends.
 *
 * @param span - The span to mark as debug-only
 *
 * @example
 * ```typescript
 * import { markDebugOnly } from '@superblocksteam/telemetry';
 *
 * tracer.startActiveSpan('debug.cache_lookup', (span) => {
 *   markDebugOnly(span);
 *   span.setAttribute('cache.key', cacheKey); // High cardinality OK
 *   // ... lookup
 *   span.end();
 * });
 * ```
 */
export declare function markDebugOnly(span: Span): void;
/**
 * Check if a span has a tier hint set.
 *
 * @param span - The span to check (must be a ReadableSpan with attributes)
 * @returns The tier hint if set, undefined otherwise
 */
export declare function getTierHint(span: {
    attributes?: Record<string, unknown>;
}): TierPolicyHint | undefined;
/**
 * Check if a tier hint indicates the span should skip Tier 2 export.
 *
 * @param hint - The tier hint to check
 * @returns true if Tier 2 should be skipped
 */
export declare function shouldSkipTier2(hint: TierPolicyHint | undefined): boolean;
/**
 * Check if a tier hint indicates the span should be included in Tier 3.
 *
 * @param hint - The tier hint to check
 * @returns true if Tier 3 should be included
 */
export declare function shouldIncludeTier3(hint: TierPolicyHint | undefined): boolean;
//# sourceMappingURL=tier-hints.d.ts.map