@odigos/aws-cdk 0.0.12 → 0.0.14

package/README.md

@@ -1,12 +1,24 @@
-# Odigos CDK constructs for AWS Lambda
+# Odigos CDK constructs for AWS
 
-Instrument AWS Lambda functions with the Odigos OpenTelemetry layer, from your own CDK app.
+Instrument AWS Lambda functions and ECS Fargate services with OpenTelemetry, from your own CDK app.
 
 ```bash
 npm install @odigos/aws-cdk        # TypeScript / JavaScript
 pip install odigos-aws-cdk         # Python
 ```
 
+| | Lambda | ECS Fargate |
+|---|---|---|
+| Construct | `OdigosLambdaInstrumentation` | `OdigosFargateInstrumentation` |
+| Mechanism | a layer, plus an exec wrapper or loader variable | agents staged into a shared task volume by a run-to-completion container |
+| Languages | python, nodejs, java, ruby | java, python, nodejs, dotnet, php, ruby |
+| Where telemetry goes | a collector in the same Lambda sandbox, which forwards | your destination, from the application process |
+| Language detection | from the function's declared runtime | none — you state the language |
+
+Both write `ODIGOS_IAC` and never the connector's ownership marker: instrumented by Odigos, owned by you.
+
+# AWS Lambda
+
 ```ts
 import { OdigosLambdaInstrumentation } from '@odigos/aws-cdk';
 
@@ -184,38 +196,22 @@ environment variable — readable by anyone with `lambda:GetFunctionConfiguratio
 console. For a long-lived credential, prefer a destination that authenticates by network position, or
 terminate at a collector you control.
 
-## Making Odigos report the function as instrumented
-
-By default these constructs do **not** write `ODIGOS_MANAGED`, and the consequence is easy to hit: Odigos
-reports the function as `Absent` — "awaiting your deployment" — even though the layer is attached, the
-wrapper is set and the collector is configured. The connector derives ownership from that one variable, and
-checks for it *before* comparing anything else, so nothing about a correctly instrumented function
-substitutes for it.
-
-For a function Odigos discovers in **manual (IaC) mode** — which is the mode a workload is in unless you
-have explicitly handed instrumentation to the connector — turn it on:
-
-```ts
-new OdigosLambdaInstrumentation(this, 'Odigos', {
-  destination: { endpoint: 'otlp.example.com:4317' },
-  functions: [fn],
-  recordOwnershipMarker: true,
-});
-```
+## How Odigos recognises the function
 
-The marker records the exact layer ARN the construct attached, which is also what the connector reads back
-to decide which layer version the function is *supposed* to carry — so a version you pinned is respected
-instead of being reported as drift. It works in `IN_ACCOUNT` mode too, where the ARN is a deploy-time
-reference your own code has no way to obtain.
+These constructs write `ODIGOS_IAC` on every function they instrument, recording the layer ARN they attached
+and the package version that attached it. That variable is what Odigos reads to attribute the function to
+itself; without it a function reports as `Absent` — "awaiting your deployment" — however completely the layer,
+wrapper and collector configuration are applied. There is nothing to switch on.
 
-It also records a rollback snapshot (`prevEnv`) naming every variable the construct set. That matters: a
-marker without one makes an uninstrument remove the **layer** while leaving `AWS_LAMBDA_EXEC_WRAPPER`
-pointing into it, which breaks the function at its next cold start. In web-server mode the snapshot holds
-your `existingLoaderValue`, so a rollback restores your own `NODE_OPTIONS` rather than deleting it.
+The recorded layer ARN matters beyond attribution: it is what the connector checks the function against, so a
+version you pinned is respected instead of being reported as drift the day Odigos publishes a newer one. It
+works in `IN_ACCOUNT` mode too, where the ARN is a deploy-time reference your own code has no way to obtain.
 
-Leave it `false` for a function you have enabled as an **automatic-mode** connector source: there the
-connector owns the marker, including a snapshot it wrote itself, and two writers of one ownership record is
-the combination that genuinely misbehaves.
+What these constructs never write is `ODIGOS_MANAGED`. That is the connector's own record of a mutation *it*
+performed, including the `prevEnv` snapshot it restores from on rollback, and it is written only when you hand
+a function to the connector by enabling it as an automatic-mode source. A CDK stack has no such snapshot to
+offer — nothing was mutated, your stack *is* the function's definition — so writing it would claim a rollback
+that was never recorded. Do not add it by hand.
 
 ## Service names
 
@@ -237,21 +233,209 @@ source ends up owned by both: each `cdk deploy` reasserts the CDK's environment,
 the connector's, and every round trip publishes a new function version.
 
 Pick one per function. Discovery-only (manual) mode is the combination that works: Odigos watches and
-reports, your stack owns the configuration — that is what `recordOwnershipMarker` is for.
+reports, your stack owns the configuration. That is what `ODIGOS_IAC` expresses — instrumented by Odigos,
+owned by you — and it is why these constructs never write the connector's ownership marker.
+
+# ECS Fargate
+
+```ts
+import { OdigosFargateInstrumentation, OdigosFargateLanguage } from '@odigos/aws-cdk';
+
+const odigos = new OdigosFargateInstrumentation(this, 'Odigos', {
+  destination: { httpEndpoint: 'https://otlp.example.com:4318' },
+});
+
+odigos.instrument({
+  container: apiContainer,          // the ecs.ContainerDefinition to instrument
+  language: OdigosFargateLanguage.JAVA,
+  service: apiService,              // read OTEL_SERVICE_NAME off the ECS service
+});
+```
+
+```python
+from odigos_aws_cdk import OdigosFargateInstrumentation, OdigosFargateLanguage
+
+odigos = OdigosFargateInstrumentation(self, "Odigos",
+    destination={"http_endpoint": "https://otlp.example.com:4318"},
+)
+odigos.instrument(
+    container=api_container,
+    language=OdigosFargateLanguage.JAVA,
+    service=api_service,
+)
+```
+
+## What it does to the task definition
+
+Four moves, which are one mechanism and only work together:
+
+1. a bare-name task volume, `odigos-agent` — on Fargate an ephemeral-storage bind mount scoped to the task
+   (there is no tmpfs);
+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 your container, which `DependsOn` the staging container
+   with condition `SUCCESS` — legal only 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 your
+   container.
+
+Marker presence alone is a false green here. A container can carry a complete, correct activation
+environment while the staging container is gone — the application then starts, finds nothing at
+`/var/odigos`, and exports nothing while reporting as instrumented. That is why all four are one construct.
+
+## Where the telemetry goes
+
+Straight to your destination, from inside the application process. **This is the substantive difference
+from Lambda**, where the SDK hands batches to a collector in the same sandbox and the export happens after
+the response has already been returned. A Fargate task has no such collector, so a slow or unreachable
+destination is felt by the application's own exporter.
+
+## Naming the service
+
+`OTEL_SERVICE_NAME` **must equal 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, so there is no default: pass `service`
+to read the name off an `ecs.FargateService`, or `serviceName` when the service is defined elsewhere.
+
+The service's physical name has to be one you set. A name CloudFormation generates is a `Ref` to the
+service, and the task definition that service runs cannot reference it — CloudFormation rejects the cycle
+at deploy time — so a generated name throws at synth pointing you at `serviceName`.
+
+## Languages, and stating them
+
+| | Activated through | Needs `runtimeVersion` |
+|---|---|---|
+| `JAVA` | `JAVA_TOOL_OPTIONS` | no |
+| `PYTHON` | `PYTHONPATH` | no |
+| `NODEJS` | `NODE_OPTIONS` | no |
+| `DOTNET` | `CORECLR_*` / `DOTNET_*` (glibc only) | no |
+| `PHP` | `PHP_INI_SCAN_DIR` | **yes** — major.minor, e.g. `"8.3"` |
+| `RUBY` | `RUBYOPT` | **yes** — major.minor, e.g. `"3.3"` |
+
+There is no aspect and no detection, and unlike Lambda that is not a matter of taste. A function declares
+its runtime; a container declares an image. A language guessed from an image would silently mis-instrument
+whatever it got wrong — a Java agent staged 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.
+
+php and ruby need `runtimeVersion` because their agents are laid down per runtime version in the bundle,
+and the version selects the path their activation variable points at. It must be exactly `major.minor`;
+anything else names a directory that does not exist, and the container starts with no agent loaded.
+
+**Go cannot be instrumented on Fargate at all.** Its only zero-code instrumentation is eBPF, and Fargate
+forbids the privileged containers and host PID an eBPF agent needs. Use the OpenTelemetry Go SDK.
+
+## Loader variables your container already sets
+
+The construct reads the value your container was created with and **appends** to it, joined by the
+separator the language's own pattern specifies — a space for `JAVA_TOOL_OPTIONS` and `NODE_OPTIONS`, a
+colon for `PYTHONPATH`:
+
+```ts
+taskDefinition.addContainer('App', {
+  image,
+  environment: { JAVA_TOOL_OPTIONS: '-Xmx512m' },
+});
+// becomes: -Xmx512m -javaagent:/var/odigos/java/javaagent.jar
+```
+
+Pass `existingLoaderValue` when the value is not visible at synth — set by an `environmentFiles` entry,
+baked into the image's own `ENV`, or supplied through `secrets`.
+
+`PHP_INI_SCAN_DIR` and `RUBYOPT` are the exception: Odigos compares them **exactly**, so they are set
+outright and a value already there is reported as a synth warning rather than merged. Fold what your
+application needs into the value Odigos sets.
+
+## Transport
+
+Each language's agent has a preferred transport, and giving the destination **both** endpoints lets each
+one take it:
+
+```ts
+destination: {
+  endpoint: 'otlp.example.com:4317',                  // OTLP/gRPC, bare host:port
+  httpEndpoint: 'https://otlp.example.com:4318',      // OTLP/HTTP, scheme-qualified
+}
+```
+
+Every agent in the bundle prefers `http/protobuf`. java, python, nodejs and dotnet honour
+`OTEL_EXPORTER_OTLP_PROTOCOL` and fall back to gRPC when that is all the destination offers; **php and
+ruby cannot** — their community SDKs are `http/protobuf`-only, so instrumenting one against a gRPC-only
+destination throws at synth rather than deploying a task that exports nothing.
+
+Endpoint and protocol are one decision, and are compared as one. Pairing an endpoint with the other
+protocol fails at runtime as a connection reset that points nowhere near the cause, so an endpoint on the
+other protocol's standard port (4317 with `http/protobuf`, 4318 with `grpc`) is a synth warning.
+
+Unlike Lambda, `destination.headers` is rendered into `OTEL_EXPORTER_OTLP_HEADERS` on the container. The
+connector does not set or compare that variable when it instruments a Fargate task itself, so it is
+neither reconciled nor reported as drift — it is here because a task with no collector of its own has
+nowhere else to hold a credential. Same exposure caveat as Lambda: `ecs:DescribeTaskDefinition` and the
+console can read it.
+
+## Signals
+
+Same defaults as Lambda — traces on, metrics and logs opt-in — and the same requirement that they match
+what Odigos has configured for the destination. All three `OTEL_*_EXPORTER` variables are written
+explicitly here, unlike Lambda where an enabled signal's variable is left unset, because the connector's
+Fargate check compares all three by value.
+
+## A task definition with more than one application
+
+Six applications in six languages in one task definition is a real shape. Call `instrument()` once per
+container; there is **one** staging container for the whole task definition, and its command is built
+lazily from the union of every instrumented container's agents, in ascending directory order — which is
+exactly what the connector compares it against.
+
+```ts
+odigos.instrumentAll([
+  { container: apiContainer,    language: OdigosFargateLanguage.JAVA,   service: svc },
+  { container: workerContainer, language: OdigosFargateLanguage.PYTHON, service: svc },
+]);
+```
+
+AWS caps a task definition at 10 containers and the staging container needs one of them; a definition
+already at the limit fails at synth rather than on `RegisterTaskDefinition`.
+
+## The agents image
+
+The staging container pulls `registry.odigos.io/odigos-fargate-agents` at this package's release tag — a
+multi-arch manifest list, so amd64 and Graviton tasks both get a matching image. **It is pulled by your
+task's execution role at every task start**, so a task in a private subnet with no NAT and no registry
+endpoint cannot pull it. Mirror it into a registry your tasks can reach and pass `agentsImage`:
+
+```ts
+agentsImage: '111122223333.dkr.ecr.eu-west-1.amazonaws.com/odigos-fargate-agents:v0.0.13',
+```
+
+A mirror has to be the same bundle — the activation environment names exact paths inside it. The bundle is
+Linux-only and glibc-based: a Windows task definition throws at synth, and musl (Alpine) images have no
+.NET native profiler in it.
+
+## Do not also instrument these services with the connector
+
+Same rule as Lambda, with ECS's own cost. The connector instruments a live service by registering a new
+task-definition revision and updating the service to it. A service instrumented here *and* enabled as an
+automatic-mode source is owned by both: each `cdk deploy` reasserts your stack's definition, each
+reconcile reasserts the connector's, and every round trip registers a revision and rolls the service.
+Discovery-only (manual) mode is the combination that works.
 
-## API
+# API
 
 | Export | |
 |---|---|
-| `OdigosLambdaInstrumentation` | the construct; `instrument(fn)`, `instrumentAll(fns)` |
+| `OdigosLambdaInstrumentation` | the Lambda construct; `instrument(fn)`, `instrumentAll(fns)` |
 | `OdigosInstrumentationAspect` | applies it to every function in a scope |
-| `OdigosDestination` | where the collector exports; exactly one of `endpoint` / `httpEndpoint` |
+| `OdigosFargateInstrumentation` | the Fargate construct; `instrument(target)`, `instrumentAll(targets)` |
+| `OdigosFargateTarget` | one container to instrument: `container`, `language`, `service` / `serviceName`, `runtimeVersion`, `existingLoaderValue` |
+| `OdigosFargateLanguage` | `JAVA` \| `PYTHON` \| `NODEJS` \| `DOTNET` \| `PHP` \| `RUBY` |
+| `OdigosDestination` | where telemetry goes; exactly one endpoint on Lambda, either or both on Fargate |
 | `OdigosLayerSource` | `ODIGOS_PUBLIC` \| `IN_ACCOUNT` |
 | `OdigosInstrumentationMode` | `HANDLER` \| `WEB_SERVER` |
 | `OdigosJavaHandlerDistro` | the four Java wrappers |
-| `recordOwnershipMarker` | the option that makes Odigos recognise the function as instrumented |
-| `renderCollectorConfig` | the collector config renderer, if you want to inspect what gets set |
+| `renderCollectorConfig` | the Lambda collector config renderer, if you want to inspect what gets set |
+| `sidecarCommand`, `evaluateAppendPattern` | the Fargate staging command and loader-value rendering |
 | `LAYER_ARNS`, `ODIGOS_VERSION` | the baked layer table and the release it came from |
+| `FARGATE_AGENTS_IMAGE`, `FARGATE_DISTROS_VERSION` | the agents image this build stages, and the distros release its recipes mirror |
 
 ## License
 

package/lib/fargate-recipes.d.ts

@@ -0,0 +1,108 @@
+import { OdigosDestination, OdigosFargateLanguage } from './types';
+/** `OTEL_EXPORTER_OTLP_PROTOCOL` values. Endpoint and protocol are always decided together. */
+export declare const OTLP_PROTOCOL_GRPC = "grpc";
+export declare const OTLP_PROTOCOL_HTTP = "http/protobuf";
+/**
+ * An append-style loader variable — `JAVA_TOOL_OPTIONS`, `NODE_OPTIONS`, `PYTHONPATH` — kept as its
+ * pattern rather than a finished value, because the value depends on what the container already carries.
+ */
+export interface FargateAppendEnvVar {
+    /** Variable name. */
+    readonly name: string;
+    /** The distro's ReplacePattern, placeholders unresolved. */
+    readonly pattern: string;
+}
+/**
+ * Resolves an append pattern for a given pre-existing value.
+ *
+ * Port of `distro.EvaluateReplacePattern`, INCLUDING the empty-original case: with nothing to join to,
+ * the placeholder and its adjacent delimiter are stripped, so the result never opens with a stray space
+ * or colon. `PYTHONPATH=":/var/odigos/python"` would put the current working directory on `sys.path`
+ * ahead of the agent, which is a different program than the one intended.
+ */
+export declare function evaluateAppendPattern(pattern: string, originalValue: string): string;
+/**
+ * The delimiter a pattern joins the container's own value to ours with: the character immediately after
+ * the original-value placeholder.
+ *
+ * DERIVED from the pattern rather than declared, because the pattern is the authority — it comes from the
+ * upstream distro, differs by language (a space for `JAVA_TOOL_OPTIONS`/`NODE_OPTIONS`, a colon for
+ * `PYTHONPATH`) and can change on somebody else's release. Assuming one would be silently destructive in
+ * a way nothing here would catch: a space-joined `PYTHONPATH` is one unusable path rather than two, and
+ * the process still starts.
+ */
+export declare function appendSeparator(pattern: string): string;
+/** One language's staging and activation, with every platform-supplied parameter already rendered. */
+export interface FargateRecipe {
+    /** Canonical language key, and the value recorded in the `ODIGOS_IAC` marker's `lang`. */
+    readonly language: string;
+    /** Directories under the agents image the staging container copies into the shared volume. */
+    readonly agentDirs: string[];
+    /** Activation variables set outright. */
+    readonly staticEnv: {
+        [key: string]: string;
+    };
+    /** Activation variables our fragment is appended to. */
+    readonly appendEnv: FargateAppendEnvVar[];
+    /** The transport this agent prefers. */
+    readonly otlpProtocol: string;
+    /** Whether the agent can speak only `otlpProtocol` and cannot be switched to the other transport. */
+    readonly protocolFixed: boolean;
+}
+/** The canonical connector language key for an enum member. The enum's values ARE those keys. */
+export declare function languageKeyOf(language: OdigosFargateLanguage): string;
+/**
+ * The recipe for a language, with the runtime version rendered into the agents' paths where the language
+ * needs it.
+ *
+ * @param runtimeVersion the application's runtime `major.minor`. Required for php and ruby, whose agent
+ * files are laid down per version, and ignored by every other language.
+ */
+export declare function recipeFor(language: OdigosFargateLanguage, runtimeVersion?: string): FargateRecipe;
+/**
+ * The staging container's command: create the shared directory, then copy each language's agent
+ * directory out of the image into it, then exit 0.
+ *
+ * ORDER AND SPELLING ARE THE CONTRACT. There is ONE staging container per task definition however many
+ * languages it holds, and the connector compares its command against the union of every instrumented
+ * container's agent directories in ascending order. A command that differs by a space is reported as
+ * drift on the whole task definition, so this is sorted and rendered exactly as `sidecarCommand` in the
+ * connector does it.
+ */
+export declare function sidecarCommand(agentDirs: string[]): string[];
+/**
+ * The resource attributes every span, metric and log from an instrumented task carries. `service.name` is
+ * set separately, through `OTEL_SERVICE_NAME`.
+ *
+ * The region may be an unresolved token on an environment-agnostic stack, which is fine here and unlike
+ * the Lambda layer lookup: this value is an environment variable, so the token resolves to a `Ref` to
+ * `AWS::Region` and CloudFormation fills in the real region at deploy time.
+ */
+export declare function fargateResourceAttributes(region: string): string;
+/** Where an instrumented container exports to, and over which transport. Always decided as a pair. */
+export interface FargateExportTarget {
+    /** `scheme://host:port`. */
+    readonly endpoint: string;
+    /** `grpc` or `http/protobuf`. */
+    readonly protocol: string;
+}
+/**
+ * Resolves the endpoint and protocol for one recipe against one destination.
+ *
+ * Port of `exportTargetFor`. A Fargate task has no node-local collector — unlike Lambda, where the SDK
+ * exports to a collector in the same sandbox — so the agent exports OTLP straight to the destination, and
+ * which transport it can use is a property of the agent as much as of the destination.
+ *
+ * Each agent's PREFERRED transport is taken when the destination offers it. When it does not, an agent
+ * whose community SDK pins the protocol (php, ruby) cannot be switched and throws; every other agent
+ * honours `OTEL_EXPORTER_OTLP_PROTOCOL` and falls back to whichever transport exists.
+ */
+export declare function exportTargetFor(recipe: FargateRecipe, dest: OdigosDestination): FargateExportTarget;
+/**
+ * A warning when an endpoint's port is the well-known port of the OTHER OTLP protocol, or "" when the
+ * pairing looks right — including a non-standard port, which cannot be judged.
+ *
+ * Worth a synth-time warning because the runtime symptom is a connection reset mid-export, which points
+ * nowhere near the cause: an HTTP request against an HTTP/2 gRPC listener, or the reverse.
+ */
+export declare function portProtocolMismatch(endpoint: string, protocol: string): string;