AWS.XRay reference

BatchGetTraces

Source: src/AWS/XRay/BatchGetTraces.ts

Retrieve full traces (all segment documents) for a list of trace IDs returned by GetTraceSummaries.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.BatchGetTracesHttp).

X-Ray trace reads are account-scoped: IAM does not support resource-level permissions for xray:BatchGetTraces, so the binding grants the action on *.

BatchGetTraces: Reading Traces

import * as XRay from "alchemy/AWS/XRay";

export default MyFunction.make(
  { main: import.meta.url, functionUrl: true, tracing: "Active" },
  Effect.gen(function* () {
    // init — bind the operation (grants xray:BatchGetTraces)
    const batchGetTraces = yield* XRay.BatchGetTraces();

    return {
      fetch: Effect.gen(function* () {
        // runtime — fetch full segment documents by trace ID
        const result = yield* batchGetTraces({
          TraceIds: ["1-63a2090f-3f4da4bcd9b1a3e07531423b"],
        });
        return yield* HttpServerResponse.json({
          segments: result.Traces?.[0]?.Segments?.length ?? 0,
        });
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(XRay.BatchGetTracesHttp)),
);

CancelTraceRetrieval

Source: src/AWS/XRay/CancelTraceRetrieval.ts

Cancel an ongoing Transaction Search trace retrieval job by its RetrievalToken.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.CancelTraceRetrievalHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:CancelTraceRetrieval, so the binding grants it on *.

CancelTraceRetrieval: Transaction Search

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:CancelTraceRetrieval
const cancelTraceRetrieval = yield* XRay.CancelTraceRetrieval();

// runtime
yield* cancelTraceRetrieval({ RetrievalToken: token });

GetInsight

Source: src/AWS/XRay/GetInsight.ts

Retrieve the summary information of an X-Ray insight — the anomaly details X-Ray detected for a group with insights enabled.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetInsightHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetInsight, so the binding grants it on *.

GetInsight: Insights

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetInsight
const getInsight = yield* XRay.GetInsight();

// runtime
const result = yield* getInsight({ InsightId: insightId });
const state = result.Insight?.State;

GetInsightEvents

Source: src/AWS/XRay/GetInsightEvents.ts

Retrieve the intermediate states (events) X-Ray recorded while re-evaluating an insight — the insight’s impact timeline.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetInsightEventsHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetInsightEvents, so the binding grants it on *.

GetInsightEvents: Insights

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetInsightEvents
const getInsightEvents = yield* XRay.GetInsightEvents();

// runtime
const result = yield* getInsightEvents({ InsightId: insightId });
const timeline = result.InsightEvents ?? [];

GetInsightImpactGraph

Source: src/AWS/XRay/GetInsightImpactGraph.ts

Retrieve a structural service graph filtered by insight — which services the insight’s anomaly impacted over a time window.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetInsightImpactGraphHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetInsightImpactGraph, so the binding grants it on *.

GetInsightImpactGraph: Insights

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetInsightImpactGraph
const getInsightImpactGraph = yield* XRay.GetInsightImpactGraph();

// runtime
const now = yield* Effect.sync(() => Date.now());
const graph = yield* getInsightImpactGraph({
  InsightId: insightId,
  StartTime: new Date(now - 60 * 60 * 1000),
  EndTime: new Date(now),
});
const services = graph.Services ?? [];

GetInsightSummaries

Source: src/AWS/XRay/GetInsightSummaries.ts

Retrieve the summaries of all insights in a group (by name or ARN) matching the provided state and time filters.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetInsightSummariesHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetInsightSummaries, so the binding grants it on *.

GetInsightSummaries: Insights

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetInsightSummaries
const getInsightSummaries = yield* XRay.GetInsightSummaries();

// runtime
const now = yield* Effect.sync(() => Date.now());
const result = yield* getInsightSummaries({
  GroupName: group.groupName,
  StartTime: new Date(now - 24 * 60 * 60 * 1000),
  EndTime: new Date(now),
});
const insights = result.InsightSummaries ?? [];

GetRetrievedTracesGraph

Source: src/AWS/XRay/GetRetrievedTracesGraph.ts

Retrieve the service graph of the traces fetched by a Transaction Search retrieval job.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetRetrievedTracesGraphHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetRetrievedTracesGraph, so the binding grants it on *.

GetRetrievedTracesGraph: Transaction Search

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetRetrievedTracesGraph
const getRetrievedTracesGraph = yield* XRay.GetRetrievedTracesGraph();

// runtime
const graph = yield* getRetrievedTracesGraph({ RetrievalToken: token });
const services = graph.Services ?? [];

GetSamplingRules

Source: src/AWS/XRay/GetSamplingRules.ts

Retrieve all X-Ray sampling rules — the first half of the sampling protocol used by custom samplers (poll rules, then report statistics via GetSamplingTargets).

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetSamplingRulesHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetSamplingRules, so the binding grants it on *.

GetSamplingRules: Sampling

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetSamplingRules
const getSamplingRules = yield* XRay.GetSamplingRules();

// runtime
const rules = yield* getSamplingRules();
const names = (rules.SamplingRuleRecords ?? []).map(
  (record) => record.SamplingRule?.RuleName,
);

GetSamplingStatisticSummaries

Source: src/AWS/XRay/GetSamplingStatisticSummaries.ts

Retrieve recent aggregate sampling results (requests matched, sampled, and borrowed) for every sampling rule.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetSamplingStatisticSummariesHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetSamplingStatisticSummaries, so the binding grants it on *.

GetSamplingStatisticSummaries: Sampling

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetSamplingStatisticSummaries
const getSamplingStatisticSummaries =
  yield* XRay.GetSamplingStatisticSummaries();

// runtime
const summaries = yield* getSamplingStatisticSummaries();
const perRule = summaries.SamplingStatisticSummaries ?? [];

GetSamplingTargets

Source: src/AWS/XRay/GetSamplingTargets.ts

Report sampling statistics and receive updated sampling quotas — the second half of the sampling protocol implemented by X-Ray SDK samplers.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetSamplingTargetsHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetSamplingTargets, so the binding grants it on *.

GetSamplingTargets: Sampling

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetSamplingTargets
const getSamplingTargets = yield* XRay.GetSamplingTargets();

// runtime — report what this client sampled and receive new quotas
const targets = yield* getSamplingTargets({
  SamplingStatisticsDocuments: [
    {
      RuleName: "my-rule",
      ClientID: "0123456789abcdef01234567",
      Timestamp: new Date(),
      RequestCount: 100,
      SampledCount: 5,
    },
  ],
});
const documents = targets.SamplingTargetDocuments ?? [];

GetServiceGraph

Source: src/AWS/XRay/GetServiceGraph.ts

Retrieve the service graph for a time window — a document describing the services processing requests and the downstream services they call.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetServiceGraphHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetServiceGraph, so the binding grants it on *.

GetServiceGraph: Service Graphs & Statistics

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetServiceGraph
const getServiceGraph = yield* XRay.GetServiceGraph();

// runtime
const now = yield* Effect.sync(() => Date.now());
const graph = yield* getServiceGraph({
  StartTime: new Date(now - 10 * 60 * 1000),
  EndTime: new Date(now),
});
const services = graph.Services ?? [];

GetTimeSeriesServiceStatistics

Source: src/AWS/XRay/GetTimeSeriesServiceStatistics.ts

Retrieve an aggregation of service statistics (response-time and error histograms) as a time series over a window, optionally filtered by group or entity selector expression.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetTimeSeriesServiceStatisticsHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetTimeSeriesServiceStatistics, so the binding grants it on *.

GetTimeSeriesServiceStatistics: Service Graphs & Statistics

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetTimeSeriesServiceStatistics
const getTimeSeriesServiceStatistics =
  yield* XRay.GetTimeSeriesServiceStatistics();

// runtime
const now = yield* Effect.sync(() => Date.now());
const stats = yield* getTimeSeriesServiceStatistics({
  StartTime: new Date(now - 10 * 60 * 1000),
  EndTime: new Date(now),
  EntitySelectorExpression: 'service("my-api")',
  Period: 60,
});
const points = stats.TimeSeriesServiceStatistics ?? [];

GetTraceGraph

Source: src/AWS/XRay/GetTraceGraph.ts

Retrieve a service graph scoped to specific trace IDs — the services and edges the given traces traversed.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetTraceGraphHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetTraceGraph, so the binding grants it on *.

GetTraceGraph: Service Graphs & Statistics

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetTraceGraph
const getTraceGraph = yield* XRay.GetTraceGraph();

// runtime
const graph = yield* getTraceGraph({
  TraceIds: ["1-63a2090f-3f4da4bcd9b1a3e07531423b"],
});
const services = graph.Services ?? [];

GetTraceSegmentDestination

Source: src/AWS/XRay/GetTraceSegmentDestination.ts

Retrieve the current destination (X-Ray or CloudWatch Logs) of data sent to PutTraceSegments and the OTLP endpoint. Transaction Search trace retrieval requires a CloudWatch Logs destination.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetTraceSegmentDestinationHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:GetTraceSegmentDestination, so the binding grants it on *.

GetTraceSegmentDestination: Transaction Search

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:GetTraceSegmentDestination
const getTraceSegmentDestination =
  yield* XRay.GetTraceSegmentDestination();

// runtime
const destination = yield* getTraceSegmentDestination();
const isTransactionSearch = destination.Destination === "CloudWatchLogs";

GetTraceSummaries

Source: src/AWS/XRay/GetTraceSummaries.ts

Retrieve IDs and annotations for traces available in a time frame, optionally filtered by an X-Ray filter expression.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.GetTraceSummariesHttp). Feed the returned trace IDs to XRay.BatchGetTraces to fetch the full segment documents.

X-Ray trace reads are account-scoped: IAM does not support resource-level permissions for xray:GetTraceSummaries, so the binding grants the action on *.

GetTraceSummaries: Reading Trace Summaries

import * as XRay from "alchemy/AWS/XRay";

export default MyFunction.make(
  { main: import.meta.url, functionUrl: true, tracing: "Active" },
  Effect.gen(function* () {
    // init — bind the operation (grants xray:GetTraceSummaries)
    const getTraceSummaries = yield* XRay.GetTraceSummaries();

    return {
      fetch: Effect.gen(function* () {
        // runtime — find traces for a service in the last 5 minutes
        const now = yield* Effect.sync(() => Date.now());
        const result = yield* getTraceSummaries({
          StartTime: new Date(now - 5 * 60 * 1000),
          EndTime: new Date(now),
          FilterExpression: 'service("my-api")',
        });
        return yield* HttpServerResponse.json({
          traceIds: (result.TraceSummaries ?? []).flatMap((summary) =>
            summary.Id ? [summary.Id] : [],
          ),
        });
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(XRay.GetTraceSummariesHttp)),
);

Group

Source: src/AWS/XRay/Group.ts

An AWS X-Ray group that collects traces matching a filter expression, for focused service maps, analytics, and insights.

Group: Creating Groups

Group traces for one service

import * as XRay from "alchemy/AWS/XRay";

const group = yield* XRay.Group("ApiGroup", {
  filterExpression: 'service("my-api")',
});

Group slow requests with insights enabled

const group = yield* XRay.Group("SlowRequests", {
  filterExpression: "responsetime > 2",
  insightsEnabled: true,
  notificationsEnabled: true,
});

ListRetrievedTraces

Source: src/AWS/XRay/ListRetrievedTraces.ts

Retrieve the traces fetched by a Transaction Search retrieval job. Returns an empty response until the job’s RetrievalStatus is COMPLETE.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.ListRetrievedTracesHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:ListRetrievedTraces, so the binding grants it on *.

ListRetrievedTraces: Transaction Search

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:ListRetrievedTraces
const listRetrievedTraces = yield* XRay.ListRetrievedTraces();

// runtime
const result = yield* listRetrievedTraces({ RetrievalToken: token });
if (result.RetrievalStatus === "COMPLETE") {
  const traces = result.Traces ?? [];
}

PutTelemetryRecords

Source: src/AWS/XRay/PutTelemetryRecords.ts

Upload telemetry about segment transmission (received/sent/rejected counts and backend connection errors) — the companion action to PutTraceSegments used by X-Ray daemons and custom emitters.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.PutTelemetryRecordsHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:PutTelemetryRecords, so the binding grants it on *.

PutTelemetryRecords: Writing Traces

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:PutTelemetryRecords
const putTelemetryRecords = yield* XRay.PutTelemetryRecords();

// runtime
yield* putTelemetryRecords({
  TelemetryRecords: [
    {
      Timestamp: new Date(),
      SegmentsReceivedCount: 10,
      SegmentsSentCount: 10,
    },
  ],
});

PutTraceSegments

Source: src/AWS/XRay/PutTraceSegments.ts

Upload segment documents to X-Ray — custom instrumentation for work the X-Ray SDK does not capture (background jobs, fan-out steps, external calls).

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.PutTraceSegmentsHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:PutTraceSegments, so the binding grants it on *.

PutTraceSegments: Writing Traces

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:PutTraceSegments
const putTraceSegments = yield* XRay.PutTraceSegments();

// runtime — record a completed unit of work as its own segment
const result = yield* putTraceSegments({
  TraceSegmentDocuments: [
    JSON.stringify({
      name: "nightly-import",
      id: "70de5b6f19ff9a0a",
      trace_id: "1-63a2090f-3f4da4bcd9b1a3e07531423b",
      start_time: 1672000000.0,
      end_time: 1672000000.5,
    }),
  ],
});
const failed = result.UnprocessedTraceSegments ?? [];

ResourcePolicy

Source: src/AWS/XRay/ResourcePolicy.ts

An X-Ray resource policy — an account-level, resource-based IAM policy that grants other Amazon Web Services services and accounts access to X-Ray, e.g. allowing SNS active tracing to send trace segments.

Resource policies are not taggable; ownership is keyed by the deterministic policy name.

ResourcePolicy: Creating Resource Policies

import * as XRay from "alchemy/AWS/XRay";

const policy = yield* XRay.ResourcePolicy("SnsActiveTracing", {
  policyDocument: JSON.stringify({
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { Service: "sns.amazonaws.com" },
        Action: ["xray:PutTraceSegments", "xray:GetSamplingRules"],
        Resource: "*",
      },
    ],
  }),
});

SamplingRule

Source: src/AWS/XRay/SamplingRule.ts

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.

SamplingRule: Creating Sampling Rules

Sample all requests to a service

import * as XRay from "alchemy/AWS/XRay";

const rule = yield* XRay.SamplingRule("SampleEverything", {
  priority: 100,
  fixedRate: 1.0,
  reservoirSize: 5,
  serviceName: "my-api-*",
});

Low-rate sampling for a noisy endpoint

const rule = yield* XRay.SamplingRule("HealthChecks", {
  priority: 10,
  fixedRate: 0.01,
  urlPath: "/health",
  httpMethod: "GET",
});

Match on segment attributes

const rule = yield* XRay.SamplingRule("PremiumTenants", {
  priority: 50,
  fixedRate: 0.5,
  reservoirSize: 1,
  attributes: { tier: "premium" },
});

StartTraceRetrieval

Source: src/AWS/XRay/StartTraceRetrieval.ts

Initiate a Transaction Search trace retrieval for the given trace IDs and time range, returning a RetrievalToken for ListRetrievedTraces and GetRetrievedTracesGraph.

Bind the operation in the function’s init phase to get a runtime callable; provide the implementation with Effect.provide(XRay.StartTraceRetrievalHttp). The action is account-scoped: X-Ray does not support resource-level permissions for xray:StartTraceRetrieval, so the binding grants it on *.

StartTraceRetrieval: Transaction Search

import * as XRay from "alchemy/AWS/XRay";

// init — grants xray:StartTraceRetrieval
const startTraceRetrieval = yield* XRay.StartTraceRetrieval();

// runtime
const now = yield* Effect.sync(() => Date.now());
const retrieval = yield* startTraceRetrieval({
  TraceIds: ["1-63a2090f-3f4da4bcd9b1a3e07531423b"],
  StartTime: new Date(now - 60 * 60 * 1000),
  EndTime: new Date(now),
});
const token = retrieval.RetrievalToken;