@odigos/aws-cdk 0.0.11 → 0.0.13

package/.jsii

@@ -3826,7 +3826,7 @@
   },
   "name": "@odigos/aws-cdk",
   "readme": {
-    "markdown": "# Odigos CDK constructs for AWS Lambda\n\nInstrument AWS Lambda functions with the Odigos OpenTelemetry layer, from your own CDK app.\n\n```bash\nnpm install @odigos/aws-cdk        # TypeScript / JavaScript\npip install odigos-aws-cdk         # Python\n```\n\n```ts\nimport { OdigosLambdaInstrumentation } from '@odigos/aws-cdk';\n\nnew OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [apiFn, workerFn],\n});\n```\n\n```python\nfrom odigos_aws_cdk import OdigosLambdaInstrumentation\n\nOdigosLambdaInstrumentation(self, \"Odigos\",\n    destination={\"endpoint\": \"otlp.example.com:4317\"},\n    functions=[api_fn, worker_fn],\n)\n```\n\nThat attaches the layer for each function's language and architecture, sets the exec wrapper that loads\nthe OpenTelemetry SDK, and hands the in-Lambda collector its whole configuration.\n\n## How the telemetry actually leaves the function\n\nYour function's SDK **does not** export to your destination. It exports to an OpenTelemetry collector\nrunning inside the same Lambda sandbox, on localhost. The collector forwards to your destination *after*\nthe handler has already returned its response.\n\nThat indirection is the whole point. A slow or unreachable destination costs billed duration, not caller\nlatency — and the collector's `decouple` processor is what holds the sandbox open until the export queue\ndrains, so a low-traffic function does not lose its telemetry to the freeze.\n\nConsequently `OTEL_EXPORTER_OTLP_ENDPOINT` is deliberately never set. If you set it yourself you put the\nexport back on the invocation's critical path.\n\n## Endpoint grammar\n\n`endpoint` is OTLP/**gRPC** as bare `host:port` (conventionally 4317). `httpEndpoint` is OTLP/**HTTP** as a\nscheme-qualified URL (conventionally 4318). Exactly one. They select different collector exporters with\ndifferent endpoint grammars, so a scheme in `endpoint` — or its absence in `httpEndpoint` — throws at synth\nrather than producing a collector that starts and silently delivers nothing. A gRPC endpoint on port 4318\n(or an HTTP one on 4317) is the likeliest version of that mistake, and is reported as a synth warning.\n\n## Choosing a layer source\n\n```ts\nnew OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [fn],\n  layerSource: OdigosLayerSource.IN_ACCOUNT,\n});\n```\n\n| | `ODIGOS_PUBLIC` (default) | `IN_ACCOUNT` |\n|---|---|---|\n| What it synthesizes | a layer ARN | an `AWS::Serverless::Application` (nested stack) per language/arch |\n| Layer owner | the Odigos AWS account | **your** account, created by your stack |\n| Resolution | synth time, from a table baked into this package | deploy time, from the Serverless Application Repository |\n| Environment-agnostic stacks | not supported — needs a concrete region | works |\n| Deploy speed | unchanged | slower on first deploy |\n\nBoth install identical bytes. `IN_ACCOUNT` exists for organisations whose policy forbids attaching a\nLambda layer owned by another AWS account. It needs the deploying principal to be allowed\n`serverlessrepo:CreateCloudFormationTemplate` and `serverlessrepo:GetApplication`.\n\nIf you mirror the layer somewhere yourself, pass `layerVersion` and neither path is used.\n\n## Versioning\n\n**The package version is the layer version.** `@odigos/aws-cdk@0.2.0` resolves to the layer built and\npublished by Odigos release `v0.2.0`, and pins the SAR application to semantic version `0.2.0` — which is\nimmutable, so it means the same bytes forever.\n\nNothing resolves at deploy time in the default path, so upgrading the layer is `npm update` and a\n`cdk diff` that shows the change. An instrumentation layer moving on its own, under a deployment that\nchanged nothing, is not a property you want.\n\n## Handler mode vs. web-server mode\n\n`OdigosInstrumentationMode.HANDLER` (the default) is for a normal Lambda handler. It sets\n`AWS_LAMBDA_EXEC_WRAPPER`.\n\n`OdigosInstrumentationMode.WEB_SERVER` is for a function running a web server behind the\n[AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter). The adapter owns the exec\nwrapper, so this mode does not touch it and loads instrumentation through the language's own loader\nvariable instead.\n\n```ts\nnew OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [webFn],\n  mode: OdigosInstrumentationMode.WEB_SERVER,\n  // NODE_OPTIONS the function already needs — ours is appended, not substituted.\n  existingLoaderValue: '--max-old-space-size=2048',\n});\n```\n\nThere is no auto-detection, deliberately. Detecting the adapter means inspecting the function's other\nlayers, which at synth time are frequently unresolved tokens; a detector that was right most of the time\nwould silently break the functions it got wrong. **Applying `HANDLER` to a web-adapter function\noverwrites the adapter's wrapper and the function stops serving.**\n\n`existingLoaderValue` has to be passed explicitly because CDK's `lambda.Function` exposes no way to read\nback an environment variable set elsewhere in your app. Omit it and the loader variable is set to the\nOdigos value alone — for `NODE_OPTIONS` that can mean losing a flag your app needs to boot.\n\nRuby has no verified web-server loader and is rejected at synth in this mode.\n\n## Java handler interfaces\n\nThe Java layer ships four wrapper scripts, one per handler interface, and this is a correctness switch\nrather than a detail level:\n\n```ts\njavaHandlerDistro: OdigosJavaHandlerDistro.OTEL_STREAM_HANDLER\n```\n\n| Distro | For |\n|---|---|\n| `OTEL_HANDLER` (default) | `RequestHandler` |\n| `OTEL_PROXY_HANDLER` | API Gateway proxy events (enriched) |\n| `OTEL_SQS_HANDLER` | SQS events (enriched) |\n| `OTEL_STREAM_HANDLER` | `RequestStreamHandler` |\n\n`OTEL_HANDLER` installs a `RequestHandler` implementation. A `RequestStreamHandler` function has a\ndifferent signature entirely, so wrapping it with the default **breaks the invocation** — it does not\nmerely produce thinner spans.\n\n## Signals\n\n```ts\ndestination: {\n  endpoint: 'otlp.example.com:4317',\n  metrics: false,   // traces and logs stay on\n}\n```\n\nA disabled signal gets no collector pipeline **and** the SDK is told not to produce it. Both halves\nmatter: a signal with no pipeline is refused at the receiver on every batch, so suppressing it at the\nsource is what stops the error loop.\n\nTurning all three off throws at synth — a collector with no pipeline fails to start, which would leave\nthe function instrumented and silent.\n\n## Instrumenting a whole stack\n\n```ts\nAspects.of(stack).add(new OdigosInstrumentationAspect(stack, {\n  destination: { endpoint: 'otlp.example.com:4317' },\n}));\n```\n\n`skipUnsupportedRuntimes` defaults to `true` for the aspect: it visits every function in the scope,\nincluding ones whose runtime has no OpenTelemetry Lambda layer (`dotnet*`, `provided.*` for Go and custom\nruntimes). Each skip is a synth warning rather than a silent no-op. The construct defaults it to `false`,\nbecause explicitly asking to instrument a Go function is a mistake worth failing on.\n\n## Credentials in `headers`\n\n`destination.headers` is rendered into `OPENTELEMETRY_COLLECTOR_CONFIG_URI`, which is a plain Lambda\nenvironment variable — readable by anyone with `lambda:GetFunctionConfiguration` and visible in the\nconsole. For a long-lived credential, prefer a destination that authenticates by network position, or\nterminate at a collector you control.\n\n## Making Odigos report the function as instrumented\n\nBy default these constructs do **not** write `ODIGOS_MANAGED`, and the consequence is easy to hit: Odigos\nreports the function as `Absent` — \"awaiting your deployment\" — even though the layer is attached, the\nwrapper is set and the collector is configured. The connector derives ownership from that one variable, and\nchecks for it *before* comparing anything else, so nothing about a correctly instrumented function\nsubstitutes for it.\n\nFor a function Odigos discovers in **manual (IaC) mode** — which is the mode a workload is in unless you\nhave explicitly handed instrumentation to the connector — turn it on:\n\n```ts\nnew OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [fn],\n  recordOwnershipMarker: true,\n});\n```\n\nThe marker records the exact layer ARN the construct attached, which is also what the connector reads back\nto decide which layer version the function is *supposed* to carry — so a version you pinned is respected\ninstead of being reported as drift. It works in `IN_ACCOUNT` mode too, where the ARN is a deploy-time\nreference your own code has no way to obtain.\n\nIt also records a rollback snapshot (`prevEnv`) naming every variable the construct set. That matters: a\nmarker without one makes an uninstrument remove the **layer** while leaving `AWS_LAMBDA_EXEC_WRAPPER`\npointing into it, which breaks the function at its next cold start. In web-server mode the snapshot holds\nyour `existingLoaderValue`, so a rollback restores your own `NODE_OPTIONS` rather than deleting it.\n\nLeave it `false` for a function you have enabled as an **automatic-mode** connector source: there the\nconnector owns the marker, including a snapshot it wrote itself, and two writers of one ownership record is\nthe combination that genuinely misbehaves.\n\n## Service names\n\nLeft unset, `OTEL_SERVICE_NAME` is the function's physical name when your stack names it explicitly, and\nthe construct id otherwise. The fallback exists because a name CloudFormation generates is a `Ref` to the\nfunction, and a function referencing itself in its own environment is a dependency cycle CloudFormation\nrejects at deploy time.\n\nThe connector compares `OTEL_SERVICE_NAME` against the workload's name in Odigos, which is the real AWS\nfunction name — so for a function whose name is generated, pass `serviceName` explicitly or it is reported\nas drifted. `serviceName` applies to **every** function a construct instruments, so use one construct per\nfunction when you want per-function names.\n\n## Do not also instrument these functions with the Odigos connector\n\nThe Odigos AWS connector instruments **live** functions by mutating them, and reconciles them back to its\nown desired state on every pass. A function instrumented here *and* enabled as an automatic-mode connector\nsource ends up owned by both: each `cdk deploy` reasserts the CDK's environment, each reconcile reasserts\nthe connector's, and every round trip publishes a new function version.\n\nPick one per function. Discovery-only (manual) mode is the combination that works: Odigos watches and\nreports, your stack owns the configuration — that is what `recordOwnershipMarker` is for.\n\n## API\n\n| Export | |\n|---|---|\n| `OdigosLambdaInstrumentation` | the construct; `instrument(fn)`, `instrumentAll(fns)` |\n| `OdigosInstrumentationAspect` | applies it to every function in a scope |\n| `OdigosDestination` | where the collector exports; exactly one of `endpoint` / `httpEndpoint` |\n| `OdigosLayerSource` | `ODIGOS_PUBLIC` \\| `IN_ACCOUNT` |\n| `OdigosInstrumentationMode` | `HANDLER` \\| `WEB_SERVER` |\n| `OdigosJavaHandlerDistro` | the four Java wrappers |\n| `recordOwnershipMarker` | the option that makes Odigos recognise the function as instrumented |\n| `renderCollectorConfig` | the collector config renderer, if you want to inspect what gets set |\n| `LAYER_ARNS`, `ODIGOS_VERSION` | the baked layer table and the release it came from |\n\n## License\n\nApache-2.0.\n"
+    "markdown": "# Odigos CDK constructs for AWS Lambda\n\nInstrument AWS Lambda functions with the Odigos OpenTelemetry layer, from your own CDK app.\n\n```bash\nnpm install @odigos/aws-cdk        # TypeScript / JavaScript\npip install odigos-aws-cdk         # Python\n```\n\n```ts\nimport { OdigosLambdaInstrumentation } from '@odigos/aws-cdk';\n\nnew OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [apiFn, workerFn],\n});\n```\n\n```python\nfrom odigos_aws_cdk import OdigosLambdaInstrumentation\n\nOdigosLambdaInstrumentation(self, \"Odigos\",\n    destination={\"endpoint\": \"otlp.example.com:4317\"},\n    functions=[api_fn, worker_fn],\n)\n```\n\nThat attaches the layer for each function's language and architecture, sets the exec wrapper that loads\nthe OpenTelemetry SDK, and hands the in-Lambda collector its whole configuration.\n\n## How the telemetry actually leaves the function\n\nYour function's SDK **does not** export to your destination. It exports to an OpenTelemetry collector\nrunning inside the same Lambda sandbox, on localhost. The collector forwards to your destination *after*\nthe handler has already returned its response.\n\nThat indirection is the whole point. A slow or unreachable destination costs billed duration, not caller\nlatency — and the collector's `decouple` processor is what holds the sandbox open until the export queue\ndrains, so a low-traffic function does not lose its telemetry to the freeze.\n\nConsequently `OTEL_EXPORTER_OTLP_ENDPOINT` is deliberately never set. If you set it yourself you put the\nexport back on the invocation's critical path.\n\n## Endpoint grammar\n\n`endpoint` is OTLP/**gRPC** as bare `host:port` (conventionally 4317). `httpEndpoint` is OTLP/**HTTP** as a\nscheme-qualified URL (conventionally 4318). Exactly one. They select different collector exporters with\ndifferent endpoint grammars, so a scheme in `endpoint` — or its absence in `httpEndpoint` — throws at synth\nrather than producing a collector that starts and silently delivers nothing. A gRPC endpoint on port 4318\n(or an HTTP one on 4317) is the likeliest version of that mistake, and is reported as a synth warning.\n\n## Choosing a layer source\n\n```ts\nnew OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [fn],\n  layerSource: OdigosLayerSource.IN_ACCOUNT,\n});\n```\n\n| | `ODIGOS_PUBLIC` (default) | `IN_ACCOUNT` |\n|---|---|---|\n| What it synthesizes | a layer ARN | an `AWS::Serverless::Application` (nested stack) per language/arch |\n| Layer owner | the Odigos AWS account | **your** account, created by your stack |\n| Resolution | synth time, from a table baked into this package | deploy time, from the Serverless Application Repository |\n| Environment-agnostic stacks | not supported — needs a concrete region | works |\n| Deploy speed | unchanged | slower on first deploy |\n\nBoth install identical bytes. `IN_ACCOUNT` exists for organisations whose policy forbids attaching a\nLambda layer owned by another AWS account. It needs the deploying principal to be allowed\n`serverlessrepo:CreateCloudFormationTemplate` and `serverlessrepo:GetApplication`.\n\nIf you mirror the layer somewhere yourself, pass `layerVersion` and neither path is used.\n\n## Versioning\n\n**The package version is the layer version.** `@odigos/aws-cdk@0.2.0` resolves to the layer built and\npublished by Odigos release `v0.2.0`, and pins the SAR application to semantic version `0.2.0` — which is\nimmutable, so it means the same bytes forever.\n\nNothing resolves at deploy time in the default path, so upgrading the layer is `npm update` and a\n`cdk diff` that shows the change. An instrumentation layer moving on its own, under a deployment that\nchanged nothing, is not a property you want.\n\n## Handler mode vs. web-server mode\n\n`OdigosInstrumentationMode.HANDLER` (the default) is for a normal Lambda handler. It sets\n`AWS_LAMBDA_EXEC_WRAPPER`.\n\n`OdigosInstrumentationMode.WEB_SERVER` is for a function running a web server behind the\n[AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter). The adapter owns the exec\nwrapper, so this mode does not touch it and loads instrumentation through the language's own loader\nvariable instead.\n\n```ts\nnew OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [webFn],\n  mode: OdigosInstrumentationMode.WEB_SERVER,\n  // NODE_OPTIONS the function already needs — ours is appended, not substituted.\n  existingLoaderValue: '--max-old-space-size=2048',\n});\n```\n\nThere is no auto-detection, deliberately. Detecting the adapter means inspecting the function's other\nlayers, which at synth time are frequently unresolved tokens; a detector that was right most of the time\nwould silently break the functions it got wrong. **Applying `HANDLER` to a web-adapter function\noverwrites the adapter's wrapper and the function stops serving.**\n\n`existingLoaderValue` has to be passed explicitly because CDK's `lambda.Function` exposes no way to read\nback an environment variable set elsewhere in your app. Omit it and the loader variable is set to the\nOdigos value alone — for `NODE_OPTIONS` that can mean losing a flag your app needs to boot.\n\nRuby has no verified web-server loader and is rejected at synth in this mode.\n\n## Java handler interfaces\n\nThe Java layer ships four wrapper scripts, one per handler interface, and this is a correctness switch\nrather than a detail level:\n\n```ts\njavaHandlerDistro: OdigosJavaHandlerDistro.OTEL_STREAM_HANDLER\n```\n\n| Distro | For |\n|---|---|\n| `OTEL_HANDLER` (default) | `RequestHandler` |\n| `OTEL_PROXY_HANDLER` | API Gateway proxy events (enriched) |\n| `OTEL_SQS_HANDLER` | SQS events (enriched) |\n| `OTEL_STREAM_HANDLER` | `RequestStreamHandler` |\n\n`OTEL_HANDLER` installs a `RequestHandler` implementation. A `RequestStreamHandler` function has a\ndifferent signature entirely, so wrapping it with the default **breaks the invocation** — it does not\nmerely produce thinner spans.\n\n## Signals\n\n**Traces only, by default.** Metrics and logs are opt-in:\n\n```ts\ndestination: {\n  endpoint: 'otlp.example.com:4317',\n  metrics: true,   // off unless you ask\n  logs: true,      // off unless you ask\n}\n```\n\nThey are opt-in because the cost of a signal the destination does not implement falls on the function:\nevery batch is refused and the in-Lambda collector retries it on an exponential backoff, inside billed\nduration. Traces are what nearly every destination accepts; the other two are a decision about your\ndestination, so they are made deliberately.\n\nA disabled signal gets no collector pipeline **and** the SDK is told not to produce it\n(`OTEL_METRICS_EXPORTER=none`). Both halves matter: a signal with no pipeline is refused at the receiver on\nevery batch, so suppressing it at the source is what stops the error loop. An enabled signal's variable\nstays unset, because `otlp` is already the SDK default.\n\n`traces: false` with neither of the others on throws at synth — a collector with no pipeline fails to\nstart, which would leave the function instrumented and silent.\n\n**If Odigos also manages this function in manual mode, the signals have to match.** The connector renders\nthe collector configuration from the destination configured in Odigos and compares the whole string, so a\ntraces-only function judged against an all-three destination is reported as drifted on the\ncollector-export component. Enable the same set on both sides.\n\n## Instrumenting a whole stack\n\n```ts\nAspects.of(stack).add(new OdigosInstrumentationAspect(stack, {\n  destination: { endpoint: 'otlp.example.com:4317' },\n}));\n```\n\n`skipUnsupportedRuntimes` defaults to `true` for the aspect: it visits every function in the scope,\nincluding ones whose runtime has no OpenTelemetry Lambda layer (`dotnet*`, `provided.*` for Go and custom\nruntimes). Each skip is a synth warning rather than a silent no-op. The construct defaults it to `false`,\nbecause explicitly asking to instrument a Go function is a mistake worth failing on.\n\n## Credentials in `headers`\n\n`destination.headers` is rendered into `OPENTELEMETRY_COLLECTOR_CONFIG_URI`, which is a plain Lambda\nenvironment variable — readable by anyone with `lambda:GetFunctionConfiguration` and visible in the\nconsole. For a long-lived credential, prefer a destination that authenticates by network position, or\nterminate at a collector you control.\n\n## How Odigos recognises the function\n\nThese constructs write `ODIGOS_IAC` on every function they instrument, recording the layer ARN they attached\nand the package version that attached it. That variable is what Odigos reads to attribute the function to\nitself; without it a function reports as `Absent` — \"awaiting your deployment\" — however completely the layer,\nwrapper and collector configuration are applied. There is nothing to switch on.\n\nThe recorded layer ARN matters beyond attribution: it is what the connector checks the function against, so a\nversion you pinned is respected instead of being reported as drift the day Odigos publishes a newer one. It\nworks in `IN_ACCOUNT` mode too, where the ARN is a deploy-time reference your own code has no way to obtain.\n\nWhat these constructs never write is `ODIGOS_MANAGED`. That is the connector's own record of a mutation *it*\nperformed, including the `prevEnv` snapshot it restores from on rollback, and it is written only when you hand\na function to the connector by enabling it as an automatic-mode source. A CDK stack has no such snapshot to\noffer — nothing was mutated, your stack *is* the function's definition — so writing it would claim a rollback\nthat was never recorded. Do not add it by hand.\n\n## Service names\n\nLeft unset, `OTEL_SERVICE_NAME` is the function's physical name when your stack names it explicitly, and\nthe construct id otherwise. The fallback exists because a name CloudFormation generates is a `Ref` to the\nfunction, and a function referencing itself in its own environment is a dependency cycle CloudFormation\nrejects at deploy time.\n\nThe connector compares `OTEL_SERVICE_NAME` against the workload's name in Odigos, which is the real AWS\nfunction name — so for a function whose name is generated, pass `serviceName` explicitly or it is reported\nas drifted. `serviceName` applies to **every** function a construct instruments, so use one construct per\nfunction when you want per-function names.\n\n## Do not also instrument these functions with the Odigos connector\n\nThe Odigos AWS connector instruments **live** functions by mutating them, and reconciles them back to its\nown desired state on every pass. A function instrumented here *and* enabled as an automatic-mode connector\nsource ends up owned by both: each `cdk deploy` reasserts the CDK's environment, each reconcile reasserts\nthe connector's, and every round trip publishes a new function version.\n\nPick one per function. Discovery-only (manual) mode is the combination that works: Odigos watches and\nreports, your stack owns the configuration. That is what `ODIGOS_IAC` expresses — instrumented by Odigos,\nowned by you — and it is why these constructs never write the connector's ownership marker.\n\n## API\n\n| Export | |\n|---|---|\n| `OdigosLambdaInstrumentation` | the construct; `instrument(fn)`, `instrumentAll(fns)` |\n| `OdigosInstrumentationAspect` | applies it to every function in a scope |\n| `OdigosDestination` | where the collector exports; exactly one of `endpoint` / `httpEndpoint` |\n| `OdigosLayerSource` | `ODIGOS_PUBLIC` \\| `IN_ACCOUNT` |\n| `OdigosInstrumentationMode` | `HANDLER` \\| `WEB_SERVER` |\n| `OdigosJavaHandlerDistro` | the four Java wrappers |\n| `renderCollectorConfig` | the collector config renderer, if you want to inspect what gets set |\n| `LAYER_ARNS`, `ODIGOS_VERSION` | the baked layer table and the release it came from |\n\n## License\n\nApache-2.0.\n"
   },
   "repository": {
     "directory": "cdk",
@@ -3852,7 +3852,7 @@
       "assembly": "@odigos/aws-cdk",
       "datatype": true,
       "docs": {
-        "remarks": "Exactly one of `endpoint` (OTLP/gRPC) and `httpEndpoint` (OTLP/HTTP) must be set. They are different\ncollector components with different endpoint grammars — `host:port` versus a scheme-qualified URL — so\nthis is a genuine branch and not a formatting difference. Setting neither, or both, throws at synth.\n\nNOTE ON THE DATA PATH. The function's SDK does not export here. It exports to the collector running\ninside the same Lambda sandbox on localhost, and the collector forwards to this destination after the\nhandler has already returned its response. That indirection is the point: a slow or unreachable\ndestination costs billed duration, not caller latency.",
+        "remarks": "Exactly one of `endpoint` (OTLP/gRPC) and `httpEndpoint` (OTLP/HTTP) must be set. They are different\ncollector components with different endpoint grammars — `host:port` versus a scheme-qualified URL — so\nthis is a genuine branch and not a formatting difference. Setting neither, or both, throws at synth.\n\nNOTE ON THE DATA PATH. The function's SDK does not export here. It exports to the collector running\ninside the same Lambda sandbox on localhost, and the collector forwards to this destination after the\nhandler has already returned its response. That indirection is the point: a slow or unreachable\ndestination costs billed duration, not caller latency.\n\nTHIS MUST DESCRIBE THE SAME DESTINATION ODIGOS HAS CONFIGURED, SIGNAL FOR SIGNAL. The connector renders\nthis same configuration from its own destination record and compares the whole rendered document against\nwhat the function carries, so any difference — the endpoint, the credential, or which of the three signals\nis enabled — is reported as instrumentation drift on the workload rather than being reconciled. The\nasymmetry to watch is the signals: `traces` is on here and `metrics`/`logs` are off, while a destination in\nOdigos commonly has more than one enabled. A stack that leaves the defaults against such a destination\nreports as drifted for a reason nothing in the stack makes visible, so read the enabled signals off the\ndestination in Odigos and state them here.",
         "stability": "stable",
         "summary": "Where the in-Lambda collector exports telemetry to."
       },
@@ -3860,7 +3860,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/types.ts",
-        "line": 102
+        "line": 111
       },
       "name": "OdigosDestination",
       "properties": [
@@ -3875,7 +3875,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/types.ts",
-            "line": 111
+            "line": 120
           },
           "name": "endpoint",
           "optional": true,
@@ -3894,7 +3894,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/types.ts",
-            "line": 139
+            "line": 148
           },
           "name": "headers",
           "optional": true,
@@ -3917,7 +3917,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/types.ts",
-            "line": 118
+            "line": 127
           },
           "name": "httpEndpoint",
           "optional": true,
@@ -3936,7 +3936,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/types.ts",
-            "line": 127
+            "line": 136
           },
           "name": "insecure",
           "optional": true,
@@ -3947,14 +3947,15 @@
         {
           "abstract": true,
           "docs": {
-            "default": "true",
+            "default": "false",
+            "remarks": "Opt-in for the same reason as `metrics`. Note that a Lambda function's stdout already reaches\nCloudWatch Logs regardless of this setting; this controls only what the OpenTelemetry SDK emits to\nthe in-Lambda collector and the collector forwards to your destination.",
             "stability": "stable",
-            "summary": "Send logs."
+            "summary": "Send logs. OFF unless you turn it on."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/types.ts",
-            "line": 164
+            "line": 185
           },
           "name": "logs",
           "optional": true,
@@ -3965,14 +3966,15 @@
         {
           "abstract": true,
           "docs": {
-            "default": "true",
+            "default": "false",
+            "remarks": "Opt-in rather than on-by-default because the cost of a signal the destination does not implement is\npaid by the function: every batch is refused and the in-Lambda collector retries it on an exponential\nbackoff, inside billed duration. Traces are what nearly every destination accepts; metrics are a\nchoice about the destination, so they are made explicitly.",
             "stability": "stable",
-            "summary": "Send metrics."
+            "summary": "Send metrics. OFF unless you turn it on."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/types.ts",
-            "line": 157
+            "line": 174
           },
           "name": "metrics",
           "optional": true,
@@ -3984,14 +3986,14 @@
           "abstract": true,
           "docs": {
             "default": "true",
-            "remarks": "A signal that is off gets no collector pipeline AND the SDK is told not to produce it\n(`OTEL_TRACES_EXPORTER=none`). Both halves matter: a signal with no pipeline is refused at the\nreceiver on every batch, so suppressing it at the source is what stops the error loop.",
+            "remarks": "A signal that is off gets no collector pipeline AND the SDK is told not to produce it\n(`OTEL_TRACES_EXPORTER=none`). Both halves matter: a signal with no pipeline is refused at the\nreceiver on every batch, so suppressing it at the source is what stops the error loop.\n\nTurning this off without turning on `metrics` or `logs` leaves the destination with no signal at all,\nwhich throws at synth — a collector with no pipeline fails to start.",
             "stability": "stable",
             "summary": "Send traces."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/types.ts",
-            "line": 150
+            "line": 162
           },
           "name": "traces",
           "optional": true,
@@ -4016,7 +4018,7 @@
         },
         "locationInModule": {
           "filename": "src/instrumentation.ts",
-          "line": 447
+          "line": 386
         },
         "parameters": [
           {
@@ -4043,7 +4045,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 439
+        "line": 378
       },
       "methods": [
         {
@@ -4053,7 +4055,7 @@
           },
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 454
+            "line": 393
           },
           "name": "visit",
           "overrides": "aws-cdk-lib.IAspect",
@@ -4084,7 +4086,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 420
+        "line": 359
       },
       "name": "OdigosInstrumentationAspectProps",
       "symbolId": "src/instrumentation:OdigosInstrumentationAspectProps"
@@ -4267,25 +4269,6 @@
             "fqn": "@odigos/aws-cdk.OdigosInstrumentationMode"
           }
         },
-        {
-          "abstract": true,
-          "docs": {
-            "default": "false",
-            "remarks": "WITHOUT IT THE FUNCTION IS REPORTED AS UNINSTRUMENTED. The connector derives ownership from this\nvariable alone: no marker means `Absent` — \"awaiting your deployment\" — even though the layer is\nattached, the wrapper is set and the collector is configured. Set this to `true` for a function that\nOdigos discovers in MANUAL (IaC) mode, which is the mode a workload is in unless you explicitly hand\ninstrumentation to the connector.\n\nLeave it `false` (the default) for a function you have enabled as an AUTOMATIC-mode connector source.\nThere, the connector instruments the function itself and owns this variable, including the `prevEnv`\nsnapshot it restores on rollback; two writers of one ownership record is the one combination that\ngenuinely misbehaves.\n\nThe marker records the exact layer ARN this construct attached, which is also what the connector reads\nback to decide which layer version the function is supposed to carry — so a version you pinned is\nrespected rather than reported as drift. It works in every layer mode, including `IN_ACCOUNT`, where the\nARN is a deploy-time reference your own code cannot obtain.",
-            "stability": "stable",
-            "summary": "Write `ODIGOS_MANAGED`, the marker that makes the Odigos connector recognise this function as instrumented."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/instrumentation.ts",
-            "line": 187
-          },
-          "name": "recordOwnershipMarker",
-          "optional": true,
-          "type": {
-            "primitive": "boolean"
-          }
-        },
         {
           "abstract": true,
           "docs": {
@@ -4316,7 +4299,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 198
+            "line": 174
           },
           "name": "skipUnsupportedRuntimes",
           "optional": true,
@@ -4378,7 +4361,7 @@
       "assembly": "@odigos/aws-cdk",
       "base": "constructs.Construct",
       "docs": {
-        "remarks": "```ts\nconst odigos = new OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [apiFn, workerFn],\n});\nodigos.instrument(anotherFn);\n```\n\nWhat it does to each function: attaches the layer for the function's language and architecture, sets\n`AWS_LAMBDA_EXEC_WRAPPER` so the layer loads the SDK, sets `OTEL_SERVICE_NAME`, and hands the in-Lambda\ncollector its entire configuration inline through `OPENTELEMETRY_COLLECTOR_CONFIG_URI`.\n\nThe function's SDK exports to the collector on localhost, not to your destination. The collector\nforwards after the handler has already returned, so a slow destination costs billed duration rather\nthan caller latency.\n\n## Do not also instrument these functions with the connector\n\nThe Odigos AWS connector instruments live functions by mutating them, and reconciles them back to its\nown desired state on every pass. A function instrumented here and also enabled as a connector source\nends up owned by both: each `cdk deploy` reasserts the CDK's environment, each reconcile reasserts the\nconnector's, and every round trip publishes a new function version.\n\nChoose one per function. This construct never sets the connector's `ODIGOS_MANAGED` ownership marker,\nso an IaC-instrumented function is not one the connector will roll back — but it will happily take it\nover if you enable it as a source.",
+        "remarks": "```ts\nconst odigos = new OdigosLambdaInstrumentation(this, 'Odigos', {\n  destination: { endpoint: 'otlp.example.com:4317' },\n  functions: [apiFn, workerFn],\n});\nodigos.instrument(anotherFn);\n```\n\nWhat it does to each function: attaches the layer for the function's language and architecture, sets\n`AWS_LAMBDA_EXEC_WRAPPER` so the layer loads the SDK, sets `OTEL_SERVICE_NAME`, and hands the in-Lambda\ncollector its entire configuration inline through `OPENTELEMETRY_COLLECTOR_CONFIG_URI`.\n\nThe function's SDK exports to the collector on localhost, not to your destination. The collector\nforwards after the handler has already returned, so a slow destination costs billed duration rather\nthan caller latency.\n\n## Do not also instrument these functions with the connector\n\nThe Odigos AWS connector instruments live functions by mutating them, and reconciles them back to its\nown desired state on every pass. A function instrumented here and also enabled as a connector source\nends up owned by both: each `cdk deploy` reasserts the CDK's environment, each reconcile reasserts the\nconnector's, and every round trip publishes a new function version.\n\nChoose one per function. This construct writes `ODIGOS_IAC` and never the connector's `ODIGOS_MANAGED`\nownership marker, so an IaC-instrumented function reports as instrumented but is not one the connector\nwill roll back — though it will happily take it over if you enable it as a source.",
         "stability": "stable",
         "summary": "Instruments AWS Lambda functions with the Odigos OpenTelemetry layer."
       },
@@ -4389,7 +4372,7 @@
         },
         "locationInModule": {
           "filename": "src/instrumentation.ts",
-          "line": 249
+          "line": 225
         },
         "parameters": [
           {
@@ -4415,7 +4398,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 243
+        "line": 219
       },
       "methods": [
         {
@@ -4426,7 +4409,7 @@
           },
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 289
+            "line": 265
           },
           "name": "instrument",
           "parameters": [
@@ -4445,7 +4428,7 @@
           },
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 322
+            "line": 298
           },
           "name": "instrumentAll",
           "parameters": [
@@ -4480,7 +4463,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 204
+        "line": 180
       },
       "name": "OdigosLambdaInstrumentationProps",
       "properties": [
@@ -4495,7 +4478,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 210
+            "line": 186
           },
           "name": "functions",
           "optional": true,
@@ -4545,6 +4528,6 @@
       "symbolId": "src/types:OdigosLayerSource"
     }
   },
-  "version": "0.0.11",
-  "fingerprint": "GhtDOF4Uik3gZvcWZlYji/v3oOcE8BiYdiH6HobYKlc="
+  "version": "0.0.13",
+  "fingerprint": "62LewgfsWUxqzy3tCKsO8Zo2MuyMvKF8j7uqckYFRoc="
 }

package/README.md

@@ -136,19 +136,33 @@ merely produce thinner spans.
 
 ## Signals
 
+**Traces only, by default.** Metrics and logs are opt-in:
+
 ```ts
 destination: {
   endpoint: 'otlp.example.com:4317',
-  metrics: false,   // traces and logs stay on
+  metrics: true,   // off unless you ask
+  logs: true,      // off unless you ask
 }
 ```
 
-A disabled signal gets no collector pipeline **and** the SDK is told not to produce it. Both halves
-matter: a signal with no pipeline is refused at the receiver on every batch, so suppressing it at the
-source is what stops the error loop.
+They are opt-in because the cost of a signal the destination does not implement falls on the function:
+every batch is refused and the in-Lambda collector retries it on an exponential backoff, inside billed
+duration. Traces are what nearly every destination accepts; the other two are a decision about your
+destination, so they are made deliberately.
+
+A disabled signal gets no collector pipeline **and** the SDK is told not to produce it
+(`OTEL_METRICS_EXPORTER=none`). Both halves matter: a signal with no pipeline is refused at the receiver on
+every batch, so suppressing it at the source is what stops the error loop. An enabled signal's variable
+stays unset, because `otlp` is already the SDK default.
+
+`traces: false` with neither of the others on throws at synth — a collector with no pipeline fails to
+start, which would leave the function instrumented and silent.
 
-Turning all three off throws at synth — a collector with no pipeline fails to start, which would leave
-the function instrumented and silent.
+**If Odigos also manages this function in manual mode, the signals have to match.** The connector renders
+the collector configuration from the destination configured in Odigos and compares the whole string, so a
+traces-only function judged against an all-three destination is reported as drifted on the
+collector-export component. Enable the same set on both sides.
 
 ## Instrumenting a whole stack
 
@@ -170,38 +184,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
 
@@ -223,7 +221,8 @@ 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.
 
 ## API
 
@@ -235,7 +234,6 @@ reports, your stack owns the configuration — that is what `recordOwnershipMark
 | `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 |
 | `LAYER_ARNS`, `ODIGOS_VERSION` | the baked layer table and the release it came from |
 

package/lib/collector-config.d.ts

@@ -43,8 +43,36 @@ export declare const EXPORTER_NONE = "none";
 export declare const ENV_TRACES_EXPORTER = "OTEL_TRACES_EXPORTER";
 export declare const ENV_METRICS_EXPORTER = "OTEL_METRICS_EXPORTER";
 export declare const ENV_LOGS_EXPORTER = "OTEL_LOGS_EXPORTER";
-/** Whether a signal is enabled, defaulting to on. */
-export declare function signalEnabled(value: boolean | undefined): boolean;
+/**
+ * Whether a signal is enabled, given the caller's value and the signal's own default.
+ *
+ * The defaults are NOT uniform: traces are on, metrics and logs are off (see `SIGNAL_DEFAULTS`). So the
+ * default has to travel with the signal rather than being folded into one "unset means on" rule.
+ */
+export declare function signalEnabled(value: boolean | undefined, defaultEnabled: boolean): boolean;
+/**
+ * Which signals a destination carries when the caller says nothing.
+ *
+ * TRACES ONLY. Metrics and logs are opt-in because the cost of having them on by default falls on people
+ * who never asked for them: a destination that does not implement a signal refuses every batch of it, and
+ * the in-Lambda collector then retries on an exponential backoff inside billed duration. Traces are what
+ * almost every destination accepts and what almost everyone instruments for; the other two are a
+ * deliberate choice about the destination, so they are made deliberately.
+ *
+ * Turning one on is `metrics: true`. Enabling a signal also drops the `OTEL_*_EXPORTER=none` override, so
+ * the SDK starts producing it again.
+ */
+export declare const SIGNAL_DEFAULTS: {
+    traces: boolean;
+    metrics: boolean;
+    logs: boolean;
+};
+/** The three signals resolved against their defaults — the single place that pairing is decided. */
+export declare function resolvedSignals(dest: OdigosDestination): {
+    traces: boolean;
+    metrics: boolean;
+    logs: boolean;
+};
 /**
  * Picks the exporter by the transport the destination configured. A destination carries a gRPC endpoint
  * (type `otlp`) or an OTLP/HTTP one (type `otlphttp`); the two are different collector components with