import * as xray from "@distilled.cloud/aws/xray";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
export interface SamplingRuleProps {
/**
* Name of the sampling rule (1-32 characters). `Default` is reserved by
* X-Ray for the built-in fallback rule.
*
* Changing the name replaces the rule.
* @default ${app}-${stage}-${id}
*/
ruleName?: string;
/**
* The priority of the sampling rule. X-Ray evaluates rules in ascending
* order of priority (`1` - `9999`) and applies the first rule that matches.
*/
priority: number;
/**
* The percentage of matching requests to instrument, after the reservoir is
* exhausted (`0.0` - `1.0`, e.g. `0.05` for 5%).
*/
fixedRate: number;
/**
* A fixed number of matching requests to instrument per second, before
* applying the fixed rate. The reservoir is not used directly by services,
* but applies to all services using the rule collectively.
* @default 0
*/
reservoirSize?: number;
/**
* Matches the `name` that the service uses to identify itself in segments.
* @default "*"
*/
serviceName?: string;
/**
* Matches the `origin` that the service uses to identify its type in
* segments (e.g. `AWS::Lambda::Function`).
* @default "*"
*/
serviceType?: string;
/**
* Matches the hostname from a request URL.
* @default "*"
*/
host?: string;
/**
* Matches the HTTP method of a request.
* @default "*"
*/
httpMethod?: string;
/**
* Matches the path from a request URL.
* @default "*"
*/
urlPath?: string;
/**
* Matches the ARN of the Amazon Web Services resource on which the service
* runs.
* @default "*"
*/
resourceArn?: string;
/**
* Matches attributes derived from the request (segment annotations).
*/
attributes?: Record<string, string>;
/**
* Tags to apply to the sampling rule. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface SamplingRule extends Resource<
"AWS.XRay.SamplingRule",
SamplingRuleProps,
{
/**
* Name of the sampling rule.
*/
ruleName: string;
/**
* ARN of the sampling rule
* (`arn:aws:xray:{region}:{account}:sampling-rule/{name}`).
*/
ruleArn: string;
},
never,
Providers
> {}
/**
* An AWS X-Ray sampling rule that controls which requests are recorded as
* traces by instrumented applications.
*
* X-Ray evaluates sampling rules in ascending priority order for each
* request. The first matching rule borrows from its reservoir, then applies
* the fixed rate.
* ### Creating Sampling Rules
* **Example:** Sample all requests to a service
* ```typescript
* import * as XRay from "@alchemy.run/aws/XRay";
*
* const rule = yield* XRay.SamplingRule("SampleEverything", {
* priority: 100,
* fixedRate: 1.0,
* reservoirSize: 5,
* serviceName: "my-api-*",
* });
* ```
*
* **Example:** Low-rate sampling for a noisy endpoint
* ```typescript
* const rule = yield* XRay.SamplingRule("HealthChecks", {
* priority: 10,
* fixedRate: 0.01,
* urlPath: "/health",
* httpMethod: "GET",
* });
* ```
*
* **Example:** Match on segment attributes
* ```typescript
* const rule = yield* XRay.SamplingRule("PremiumTenants", {
* priority: 50,
* fixedRate: 0.5,
* reservoirSize: 1,
* attributes: { tier: "premium" },
* });
* ```
*
* @resource
*/
export const SamplingRule = Resource<SamplingRule>("AWS.XRay.SamplingRule");
/**
* Raised when a `SamplingRule` is configured with the reserved rule name
* `Default`, which X-Ray uses for the built-in fallback rule.
*/
export class XRayReservedRuleName extends Data.TaggedError("XRayReservedRuleName")<{
message: string;
}> {}
const validateRuleName = (props: Pick<SamplingRuleProps, "ruleName">) =>
props.ruleName === "Default"
? Effect.fail(
new XRayReservedRuleName({
message:
'"Default" is reserved for the built-in X-Ray fallback sampling rule — choose another ruleName.',
}),
)
: Effect.void;
const shallowRecordEqual = (
a: Record<string, string | undefined>,
b: Record<string, string | undefined>,
) => {
const aKeys = Object.keys(a).filter((k) => a[k] !== undefined);
const bKeys = Object.keys(b).filter((k) => b[k] !== undefined);
return aKeys.length === bKeys.length && aKeys.every((key) => a[key] === b[key]);
};
export const SamplingRuleProvider = () =>
Provider.effect(
SamplingRule,
Effect.gen(function* () {
const createRuleName = Effect.fn(function* (
id: string,
props: Pick<SamplingRuleProps, "ruleName">,
) {
// X-Ray rule names are limited to 32 characters.
return props.ruleName ?? (yield* createPhysicalName({ id, maxLength: 32 }));
});
// The desired wire shape for both create and update, derived purely
// from the new props.
const desiredRule = (name: string, props: SamplingRuleProps) => ({
RuleName: name,
ResourceARN: props.resourceArn ?? "*",
Priority: props.priority,
FixedRate: props.fixedRate,
ReservoirSize: props.reservoirSize ?? 0,
ServiceName: props.serviceName ?? "*",
ServiceType: props.serviceType ?? "*",
Host: props.host ?? "*",
HTTPMethod: props.httpMethod ?? "*",
URLPath: props.urlPath ?? "*",
Attributes: props.attributes ?? {},
});
// X-Ray has no GetSamplingRule — observe by enumerating the (small)
// rule list and matching on the deterministic rule name.
const observeRule = (name: string) =>
xray.getSamplingRules.items({}).pipe(
Stream.filter((record) => record.SamplingRule?.RuleName === name),
Stream.runHead,
Effect.map((record) => Option.getOrUndefined(record)?.SamplingRule),
);
const observedTags = (ruleArn: string) =>
xray.listTagsForResource.items({ ResourceARN: ruleArn }).pipe(
Stream.runCollect,
Effect.map((chunk) => Object.fromEntries(Array.from(chunk).map((t) => [t.Key, t.Value]))),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed({} as Record<string, string>),
),
);
return SamplingRule.Provider.of({
stables: ["ruleName", "ruleArn"],
list: () =>
Effect.gen(function* () {
const records = yield* xray.getSamplingRules.items({}).pipe(Stream.runCollect);
return Array.from(records).flatMap((record) =>
record.SamplingRule?.RuleName &&
record.SamplingRule.RuleARN &&
// The built-in `Default` sampling rule always exists and can
// never be deleted — keep it out of enumeration for
// account-wide teardown (nuke).
record.SamplingRule.RuleName !== "Default"
? [
{
ruleName: record.SamplingRule.RuleName,
ruleArn: record.SamplingRule.RuleARN,
},
]
: [],
);
}),
read: Effect.fn(function* ({ id, olds, output }) {
const ruleName = output?.ruleName ?? (yield* createRuleName(id, olds ?? {}));
const found = yield* observeRule(ruleName);
if (!found?.RuleARN) return undefined;
const attrs = { ruleName, ruleArn: found.RuleARN };
const tags = yield* observedTags(found.RuleARN);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
yield* validateRuleName(news ?? {});
const oldName = yield* createRuleName(id, olds ?? {});
const newName = yield* createRuleName(id, news ?? {});
if (oldName !== newName) {
return { action: "replace" } as const;
}
// fall through: engine default update logic for mutable fields
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
yield* validateRuleName(news);
const ruleName = output?.ruleName ?? (yield* createRuleName(id, news));
const desired = desiredRule(ruleName, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// 1. OBSERVE — the rule list is authoritative; output is only a
// cached identifier.
let live = yield* observeRule(ruleName);
// 2. ENSURE — create when missing; a concurrent create surfaces as
// the typed SamplingRuleAlreadyExists tag, which we treat as a
// race and re-observe.
if (live === undefined) {
live = yield* xray
.createSamplingRule({
SamplingRule: { ...desired, Version: 1 },
Tags: createTagsList(desiredTags),
})
.pipe(
Effect.map((r) => r.SamplingRuleRecord?.SamplingRule),
Effect.catchTag("SamplingRuleAlreadyExists", () => observeRule(ruleName)),
);
}
// 3. SYNC — diff every mutable field of the OBSERVED rule against
// the desired shape; a single UpdateSamplingRule applies the
// full desired state only when something actually drifted.
const inSync =
live !== undefined &&
live.ResourceARN === desired.ResourceARN &&
live.Priority === desired.Priority &&
live.FixedRate === desired.FixedRate &&
live.ReservoirSize === desired.ReservoirSize &&
live.ServiceName === desired.ServiceName &&
live.ServiceType === desired.ServiceType &&
live.Host === desired.Host &&
live.HTTPMethod === desired.HTTPMethod &&
live.URLPath === desired.URLPath &&
shallowRecordEqual(live.Attributes ?? {}, desired.Attributes);
if (!inSync) {
live = yield* xray
.updateSamplingRule({ SamplingRuleUpdate: desired })
.pipe(Effect.map((r) => r.SamplingRuleRecord?.SamplingRule));
}
// The ARN shape is deterministic:
// arn:aws:xray:{region}:{account}:sampling-rule/{name}
const { accountId, region } = yield* AWSEnvironment.current;
const ruleArn =
live?.RuleARN ?? `arn:aws:xray:${region}:${accountId}:sampling-rule/${ruleName}`;
// 3b. SYNC TAGS — diff against OBSERVED cloud tags so adoption
// converges (create-time Tags only apply on first create).
const currentTags = yield* observedTags(ruleArn);
const { upsert, removed } = diffTags(currentTags, desiredTags);
if (upsert.length > 0) {
yield* xray.tagResource({ ResourceARN: ruleArn, Tags: upsert });
}
if (removed.length > 0) {
yield* xray.untagResource({
ResourceARN: ruleArn,
TagKeys: removed,
});
}
yield* session.note(ruleName);
return { ruleName, ruleArn };
}),
delete: Effect.fn(function* ({ output }) {
yield* xray.deleteSamplingRule({ RuleName: output.ruleName }).pipe(
// Typed synthetic tag for a missing rule — idempotent delete.
Effect.catchTag("SamplingRuleNotFound", () => Effect.void),
);
}),
});
}),
);