@odigos/aws-cdk 0.0.13 → 0.0.14

package/lib/fargate.d.ts

@@ -0,0 +1,218 @@
+import * as ecs from 'aws-cdk-lib/aws-ecs';
+import { Construct } from 'constructs';
+import { OdigosDestination, OdigosFargateLanguage } from './types';
+/**
+ * Options shared by every container this construct instruments.
+ */
+export interface OdigosFargateInstrumentationOptions {
+    /**
+     * Where the instrumented containers export telemetry to.
+     *
+     * Unlike Lambda, BOTH transports may be set and often should be: a Fargate task has no collector of its
+     * own, so each language's agent exports to this destination itself and takes the transport it prefers.
+     * php and ruby can only speak OTLP/HTTP at all.
+     */
+    readonly destination: OdigosDestination;
+    /**
+     * The agents bundle the staging container copies the language agents out of.
+     *
+     * Defaults to the multi-arch image this package's release published, at that release's immutable tag.
+     * Override it to mirror the image into a registry your tasks can reach — the image is pulled by YOUR
+     * task's execution role at every task start, so a task in a private subnet with no NAT and no
+     * interface endpoint cannot pull the default.
+     *
+     * A mirror must be the same bundle: the activation environment set below names exact paths inside it.
+     *
+     * @default - the released `registry.odigos.io/odigos-fargate-agents` image for this package version
+     */
+    readonly agentsImage?: string;
+    /**
+     * Raise agent verbosity (`OTEL_LOG_LEVEL=debug`) on every instrumented container.
+     *
+     * Useful while wiring up a destination, expensive to leave on — and it is compared: the connector
+     * expects the variable ABSENT unless debug telemetry is enabled for the connector too, so leaving this
+     * on can itself be reported as drift.
+     *
+     * @default false
+     */
+    readonly debug?: boolean;
+}
+/**
+ * One container to instrument.
+ */
+export interface OdigosFargateTarget {
+    /**
+     * The application container. Its task definition is taken from it, so the staging container, the shared
+     * volume and the startup dependency are added to the right one automatically.
+     */
+    readonly container: ecs.ContainerDefinition;
+    /**
+     * The language whose agent to stage and activate.
+     *
+     * Stated rather than detected — a container declares an image, not a runtime, and resolving a language
+     * from an image means pulling it.
+     */
+    readonly language: OdigosFargateLanguage;
+    /**
+     * `OTEL_SERVICE_NAME` for this container.
+     *
+     * THIS MUST MATCH THE WORKLOAD'S NAME IN ODIGOS, which for a Fargate workload is the ECS SERVICE name —
+     * not the task definition family and not the container name. A different value is reported as
+     * instrumentation drift rather than treated as a naming preference.
+     *
+     * Pass `service` instead to read it off the service, or set this when the service is defined elsewhere
+     * (a different stack, Terraform, the console). One of the two is required.
+     *
+     * @default - taken from `service`
+     */
+    readonly serviceName?: string;
+    /**
+     * The ECS service that runs this task definition, used only to read its name.
+     *
+     * Its physical name has to be one your stack SET, not one CloudFormation generates: a generated name is
+     * a `Ref` to the service, and a service's own task definition referencing it is a dependency cycle
+     * CloudFormation rejects at deploy time. A generated name throws at synth pointing at `serviceName`.
+     *
+     * @default - `serviceName` must be given instead
+     */
+    readonly service?: ecs.BaseService;
+    /**
+     * The application's runtime version as `major.minor` — for example `"8.3"`.
+     *
+     * Required for php and ruby, whose agents are laid down per runtime version in the bundle, and the
+     * version selects the path their activation variables point at. Ignored by every other language.
+     *
+     * @default - none; required for php and ruby
+     */
+    readonly runtimeVersion?: string;
+    /**
+     * The value this container already needs in its loader variable (`JAVA_TOOL_OPTIONS`, `NODE_OPTIONS` or
+     * `PYTHONPATH`), which the Odigos fragment is joined to rather than replacing.
+     *
+     * Only needed as an OVERRIDE. The construct reads the value the container was created with and appends
+     * to it, so a container that sets its own `JAVA_TOOL_OPTIONS` in `addContainer` keeps it. Pass this when
+     * the value is not visible at synth — set by an `environmentFiles` entry, injected by the image's own
+     * `ENV`, or supplied through `secrets`.
+     *
+     * @default - read from the container's own environment
+     */
+    readonly existingLoaderValue?: string;
+}
+/**
+ * Props for {@link OdigosFargateInstrumentation}.
+ */
+export interface OdigosFargateInstrumentationProps extends OdigosFargateInstrumentationOptions {
+    /**
+     * Containers to instrument on construction. More can be added with `instrument()`.
+     *
+     * @default - none
+     */
+    readonly targets?: OdigosFargateTarget[];
+}
+/**
+ * Instruments ECS Fargate containers with the Odigos OpenTelemetry agents.
+ *
+ * ```ts
+ * const odigos = new OdigosFargateInstrumentation(this, 'Odigos', {
+ *   destination: { httpEndpoint: 'https://otlp.example.com:4318' },
+ * });
+ * odigos.instrument({
+ *   container: apiContainer,
+ *   language: OdigosFargateLanguage.JAVA,
+ *   service: apiService,
+ * });
+ * ```
+ *
+ * ## What it does to the task definition
+ *
+ * Four moves, which are one mechanism and only work together — the ECS adaptation of the Odikos
+ * init-container mount method:
+ *
+ *  1. a bare-name task volume (`odigos-agent`), which on Fargate is an ephemeral-storage bind mount
+ *     scoped to the task;
+ *  2. a NON-ESSENTIAL `odigos-agent` container that copies the language agents out of the agents bundle
+ *     into that volume and exits 0;
+ *  3. the volume mounted read-only at `/var/odigos` in each instrumented container, which depends on the
+ *     staging container with condition `SUCCESS` — only valid against a non-essential container, which is
+ *     why (2) is non-essential;
+ *  4. the language's activation environment, the OTLP export environment, and the `ODIGOS_IAC` marker on
+ *     each instrumented container.
+ *
+ * There is ONE staging container per task definition however many languages the task holds; its command
+ * is the union of every instrumented container's agent directories, and it is built lazily so containers
+ * instrumented later are included.
+ *
+ * ## Where the telemetry goes
+ *
+ * Straight to your destination, from inside the application process. This is the substantive difference
+ * from Lambda: there is no collector in the task to hand a batch to, so a slow or unreachable destination
+ * is felt by the application's own exporter rather than absorbed after a response has been returned.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * There is no aspect that sweeps a scope, as there is for Lambda. An aspect there works because a
+ * function DECLARES its runtime; a container declares an image, and a language guessed from an image name
+ * would silently mis-instrument the ones it got wrong — staging a Java agent into a Python container
+ * leaves it uninstrumented, and a `JAVA_TOOL_OPTIONS` on a JVM-less image is simply ignored, so nothing
+ * fails loudly enough to notice.
+ *
+ * ## Do not also instrument these services with the connector
+ *
+ * The connector instruments live services by registering a new task-definition revision and updating the
+ * service to it, reconciling to its own desired state on every pass. A service instrumented here and also
+ * enabled as a connector source ends up owned by both: each `cdk deploy` reasserts the stack's
+ * definition, each reconcile reasserts the connector's, and every round trip registers a revision and
+ * rolls the service. Choose one per service.
+ */
+export declare class OdigosFargateInstrumentation extends Construct {
+    private readonly options;
+    private readonly agentsImage;
+    private readonly taskDefinitions;
+    private readonly instrumented;
+    constructor(scope: Construct, id: string, props: OdigosFargateInstrumentationProps);
+    /**
+     * Instruments one container. Idempotent — instrumenting the same container twice is a no-op rather than
+     * a doubled loader value.
+     */
+    instrument(target: OdigosFargateTarget): void;
+    /** Instruments every target in the list. */
+    instrumentAll(targets: OdigosFargateTarget[]): void;
+    /**
+     * The task definition's staging container and volume, created once and shared by every container in it.
+     *
+     * The command is a lazy list rather than a literal because the union it renders is not known until
+     * synthesis: a task definition holding a Java and a Python application is instrumented by two
+     * `instrument()` calls, and the single staging container has to stage both. The connector compares this
+     * command against exactly that union, so a stale one is reported as drift on the whole task definition
+     * and leaves one of the containers with no agent on disk.
+     */
+    private taskDefinitionState;
+    /**
+     * `OTEL_SERVICE_NAME` for a target, and the one value a caller cannot be allowed to leave to a default.
+     *
+     * The connector compares it against the workload's name in Odigos, which is the ECS SERVICE name, so
+     * guessing — the task definition family, the container name, the construct id — would produce a stack
+     * that deploys cleanly and then reports as drifted on a component nothing in the stack makes visible.
+     *
+     * Read from the L1, not from `service.serviceName`: the L2 property is a token that resolves to a `Ref`
+     * to the service even when the stack set the name explicitly, and a `Ref` here is worse than useless —
+     * the task definition would reference the service that references it, which CloudFormation rejects as a
+     * dependency cycle at deploy time.
+     */
+    private resolveServiceName;
+    /**
+     * Checks the task definition can carry the staged-agent method at all, and warns about the things that
+     * are legal but almost certainly a mistake.
+     */
+    private checkTaskDefinition;
+    /**
+     * The environment applied to one instrumented container.
+     *
+     * Mirrors `instrumentContainer` in the connector, including the ORDER of decisions: the agent's own
+     * activation variables first, then identity, then export, then the marker. Every variable here has a
+     * counterpart in the connector's `containerDiff`, which is what a customer's conformance report is
+     * built from — so one that is absent, or spelled differently, is reported as a named broken component
+     * rather than passing quietly.
+     */
+    private environmentFor;
+}