@odigos/aws-cdk 0.0.10 → 0.0.12

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## 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## 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 a connector source ends up\nowned 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\nPick one per function. These constructs never set the connector's `ODIGOS_MANAGED` ownership marker — so\nan IaC-instrumented function is not one the connector will roll back — but the connector will take it\nover if you enable it as a source.\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"
+    "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## 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"
   },
   "repository": {
     "directory": "cdk",
@@ -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": 176
           },
           "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": 165
           },
           "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": 153
           },
           "name": "traces",
           "optional": true,
@@ -4016,7 +4018,7 @@
         },
         "locationInModule": {
           "filename": "src/instrumentation.ts",
-          "line": 339
+          "line": 448
         },
         "parameters": [
           {
@@ -4043,7 +4045,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 331
+        "line": 440
       },
       "methods": [
         {
@@ -4053,7 +4055,7 @@
           },
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 346
+            "line": 455
           },
           "name": "visit",
           "overrides": "aws-cdk-lib.IAspect",
@@ -4084,7 +4086,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 312
+        "line": 421
       },
       "name": "OdigosInstrumentationAspectProps",
       "symbolId": "src/instrumentation:OdigosInstrumentationAspectProps"
@@ -4134,7 +4136,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 67
+        "line": 85
       },
       "name": "OdigosInstrumentationOptions",
       "properties": [
@@ -4147,7 +4149,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 71
+            "line": 89
           },
           "name": "destination",
           "type": {
@@ -4165,7 +4167,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 123
+            "line": 141
           },
           "name": "debug",
           "optional": true,
@@ -4184,7 +4186,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 145
+            "line": 163
           },
           "name": "existingLoaderValue",
           "optional": true,
@@ -4203,7 +4205,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 96
+            "line": 114
           },
           "name": "javaHandlerDistro",
           "optional": true,
@@ -4221,7 +4223,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 78
+            "line": 96
           },
           "name": "layerSource",
           "optional": true,
@@ -4240,7 +4242,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 133
+            "line": 151
           },
           "name": "layerVersion",
           "optional": true,
@@ -4259,7 +4261,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 89
+            "line": 107
           },
           "name": "mode",
           "optional": true,
@@ -4267,6 +4269,25 @@
             "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": {
@@ -4278,7 +4299,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 111
+            "line": 129
           },
           "name": "serviceName",
           "optional": true,
@@ -4297,7 +4318,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 156
+            "line": 198
           },
           "name": "skipUnsupportedRuntimes",
           "optional": true,
@@ -4370,7 +4391,7 @@
         },
         "locationInModule": {
           "filename": "src/instrumentation.ts",
-          "line": 207
+          "line": 249
         },
         "parameters": [
           {
@@ -4396,7 +4417,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 201
+        "line": 243
       },
       "methods": [
         {
@@ -4407,7 +4428,7 @@
           },
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 226
+            "line": 289
           },
           "name": "instrument",
           "parameters": [
@@ -4426,7 +4447,7 @@
           },
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 257
+            "line": 322
           },
           "name": "instrumentAll",
           "parameters": [
@@ -4461,7 +4482,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/instrumentation.ts",
-        "line": 162
+        "line": 204
       },
       "name": "OdigosLambdaInstrumentationProps",
       "properties": [
@@ -4476,7 +4497,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/instrumentation.ts",
-            "line": 168
+            "line": 210
           },
           "name": "functions",
           "optional": true,
@@ -4526,6 +4547,6 @@
       "symbolId": "src/types:OdigosLayerSource"
     }
   },
-  "version": "0.0.10",
-  "fingerprint": "fx+B66BFFPxbnPyQDWebGpotmbtitQSQDn87AebqIa8="
+  "version": "0.0.12",
+  "fingerprint": "76adPuc8StHhgh9x1dH8rP9GBtLmzzNKY1d5Dvhv+hM="
 }

package/README.md

@@ -41,6 +41,14 @@ drains, so a low-traffic function does not lose its telemetry to the freeze.
 Consequently `OTEL_EXPORTER_OTLP_ENDPOINT` is deliberately never set. If you set it yourself you put the
 export back on the invocation's critical path.
 
+## Endpoint grammar
+
+`endpoint` is OTLP/**gRPC** as bare `host:port` (conventionally 4317). `httpEndpoint` is OTLP/**HTTP** as a
+scheme-qualified URL (conventionally 4318). Exactly one. They select different collector exporters with
+different endpoint grammars, so a scheme in `endpoint` — or its absence in `httpEndpoint` — throws at synth
+rather than producing a collector that starts and silently delivers nothing. A gRPC endpoint on port 4318
+(or an HTTP one on 4317) is the likeliest version of that mistake, and is reported as a synth warning.
+
 ## Choosing a layer source
 
 ```ts
@@ -128,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.
 
-Turning all three off throws at synth — a collector with no pipeline fails to start, which would leave
-the function instrumented and silent.
+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.
+
+**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
 
@@ -162,16 +184,60 @@ 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,
+});
+```
+
+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.
+
+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.
+
+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.
+
+## Service names
+
+Left unset, `OTEL_SERVICE_NAME` is the function's physical name when your stack names it explicitly, and
+the construct id otherwise. The fallback exists because a name CloudFormation generates is a `Ref` to the
+function, and a function referencing itself in its own environment is a dependency cycle CloudFormation
+rejects at deploy time.
+
+The connector compares `OTEL_SERVICE_NAME` against the workload's name in Odigos, which is the real AWS
+function name — so for a function whose name is generated, pass `serviceName` explicitly or it is reported
+as drifted. `serviceName` applies to **every** function a construct instruments, so use one construct per
+function when you want per-function names.
+
 ## Do not also instrument these functions with the Odigos connector
 
 The Odigos AWS connector instruments **live** functions by mutating them, and reconciles them back to its
-own desired state on every pass. A function instrumented here *and* enabled as a connector source ends up
-owned by both: each `cdk deploy` reasserts the CDK's environment, each reconcile reasserts the
-connector's, and every round trip publishes a new function version.
+own desired state on every pass. A function instrumented here *and* enabled as an automatic-mode connector
+source ends up owned by both: each `cdk deploy` reasserts the CDK's environment, each reconcile reasserts
+the connector's, and every round trip publishes a new function version.
 
-Pick one per function. These constructs never set the connector's `ODIGOS_MANAGED` ownership marker — so
-an IaC-instrumented function is not one the connector will roll back — but the connector will take it
-over if you enable it as a source.
+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.
 
 ## API
 
@@ -183,6 +249,7 @@ over if you enable it as a source.
 | `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