strands-token-telemetry 0.1.0__tar.gz

strands_token_telemetry-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+# Publish to PyPI when a GitHub Release is published.
+#
+# Setup required (one-time):
+#   1. In this repo's Settings > Environments, create an environment named "pypi".
+#   2. On PyPI, go to your project > Publishing > Add a new publisher:
+#        - Owner: flockcover
+#        - Repository: strands-token-telemetry
+#        - Workflow: publish.yml
+#        - Environment: pypi
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

strands_token_telemetry-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.pytest_cache/
+.ruff_cache/
+.claude/
+.devcontainer/

strands_token_telemetry-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strands_token_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: strands-token-telemetry
+Version: 0.1.0
+Summary: Emit Strands agent token usage as CloudWatch EMF metrics
+Project-URL: Homepage, https://github.com/flockcover/strands-token-telemetry
+Project-URL: Issues, https://github.com/flockcover/strands-token-telemetry/issues
+Author-email: Tom Harvey <tom.harvey@flockcover.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: strands-agents>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# strands-token-telemetry
+
+Emit [Strands Agents](https://github.com/strands-agents/sdk-python) token usage as [CloudWatch EMF](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) metrics.
+
+## Why this library?
+
+Strands Agents has built-in observability via OpenTelemetry traces, and AgentCore adds automatic CloudWatch metrics — but this turnkey telemetry only works when you use **BedrockModel** and deploy to **AgentCore**.
+
+If you're already on BedrockModel + AgentCore, you may not need this. Otherwise, this library fills three gaps:
+
+1. **Works with any model provider** — not locked into BedrockModel. Use Anthropic, LiteLLM, Ollama, or any Strands-compatible model and still get token metrics.
+
+2. **Works on any infrastructure** — ECS, Lambda, EC2, on-prem, or AgentCore. Anywhere the CloudWatch agent (or a compatible log sink) runs, you get first-class CloudWatch Metrics.
+
+3. **First-class CloudWatch Metrics, not trace attributes** — Strands' OTEL integration captures token counts as span attributes buried in traces. EMF creates real CloudWatch Metrics you can directly alarm on, dashboard, and apply metric math to (e.g. cost estimation). No OTEL collector setup or ADOT config required — just stdout.
+
+| | Strands OTEL traces | AgentCore auto-telemetry | This library |
+|---|---|---|---|
+| Any model provider | Yes | BedrockModel only | Yes |
+| Any deploy target | Yes | AgentCore only | Yes |
+| CloudWatch Metrics | No (span attributes) | Yes | Yes |
+| CloudWatch Alarms | No | Yes | Yes |
+| OTEL collector needed | Yes | Managed | No |
+| Setup | Configure ADOT/exporter | Deploy to AgentCore | One hook, one line |
+
+## Install
+
+```bash
+pip install strands-token-telemetry
+```
+
+`strands-agents` is a peer dependency — install it separately (or it's likely already in your project).
+
+## AI-assisted integration
+
+### For developers
+
+Copy and paste this prompt into Claude Code, Cursor, or your preferred AI coding
+assistant:
+
+> Install strands-token-telemetry and add a TokenUsageHook to my Strands agent.
+> Read the integration guide at
+> https://raw.githubusercontent.com/flockcover/strands-token-telemetry/main/docs/llms.txt
+> before writing any code.
+
+### For AI coding assistants
+
+If you are an AI coding assistant helping a developer integrate this library,
+fetch the full API reference and integration patterns from the LLM-optimized
+docs before generating code:
+
+    https://raw.githubusercontent.com/flockcover/strands-token-telemetry/main/docs/llms.txt
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_token_telemetry import TokenUsageHook
+
+agent = Agent(hooks=[TokenUsageHook()])
+```
+
+Every agent invocation prints a JSON line to stdout in [CloudWatch EMF](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) format. The CloudWatch agent picks this up and publishes metrics automatically.
+
+### Adding session context
+
+A common pattern is tagging metrics with a custom namespace plus user and session
+identifiers so you can filter and query them in CloudWatch Insights. Pass static
+dimension values for the model, and `extra_properties` for fields that should be
+searchable but not published as metric dimensions:
+
+```python
+from strands import Agent
+from strands_token_telemetry import TokenUsageHook
+
+hook = TokenUsageHook(
+    namespace="AcmeInc/StrandsTokens",
+    dimension_values={"Model": model_id},
+    extra_properties={"UserId": user_id, "SessionId": session_id},
+)
+agent = Agent(hooks=[hook])
+```
+
+`Model` appears as a CloudWatch Metric dimension you can alarm on, while `UserId`
+and `SessionId` stay as top-level properties queryable with CloudWatch Insights
+(e.g. `filter SessionId = "abc-123"`).
+
+Each invocation emits a single JSON line like this (pretty-printed here for
+readability):
+
+```json
+{
+  "_aws": {
+    "Timestamp": 1700000000000,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "AcmeInc/StrandsTokens",
+        "Dimensions": [["Model"]],
+        "Metrics": [
+          { "Name": "inputTokens", "Unit": "Count" },
+          { "Name": "outputTokens", "Unit": "Count" },
+          { "Name": "totalTokens", "Unit": "Count" },
+          { "Name": "cacheReadInputTokens", "Unit": "Count" },
+          { "Name": "cacheWriteInputTokens", "Unit": "Count" }
+        ]
+      }
+    ]
+  },
+  "Model": "us.anthropic.claude-sonnet-4-20250514",
+  "UserId": "user-42",
+  "SessionId": "abc-123",
+  "inputTokens": 1024,
+  "outputTokens": 256,
+  "totalTokens": 1280,
+  "cacheReadInputTokens": 512,
+  "cacheWriteInputTokens": 0
+}
+```
+
+## Configuration
+
+All constructor parameters are keyword-only.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `namespace` | `str` | `"Strands/AgentTokenUsage"` | CloudWatch metrics namespace |
+| `dimensions` | `list[list[str]]` | `[["Model"]]` | Dimension key sets |
+| `dimension_values` | `dict[str, str]` | `{}` | Static dimension key/value pairs |
+| `dimension_resolver` | `Callable` | `None` | Receives `AfterInvocationEvent`, returns dynamic dimension values |
+| `extra_properties` | `dict[str, Any]` | `None` | Extra top-level properties (searchable in CloudWatch Insights) |
+| `emitter` | `Callable` | `default_emitter` | Function that receives the payload dict |
+
+## Dynamic dimensions
+
+Use `dimension_resolver` when a dimension value isn't known until the agent runs — for example, the model name returned by the provider, or an agent identifier pulled from the event. Static values like environment or service name can go in `dimension_values`; the resolver handles everything that changes per invocation.
+
+```python
+def resolve_dims(event):
+    model = getattr(event.result, "model", "unknown") if event.result else "unknown"
+    return {"Model": model}
+
+agent = Agent(hooks=[
+    TokenUsageHook(
+        dimensions=[["Model", "Environment"]],
+        dimension_values={"Environment": "prod"},
+        dimension_resolver=resolve_dims,
+    )
+])
+```
+
+A more advanced example — splitting metrics by both model and a per-request agent name:
+
+```python
+def resolve_dims(event):
+    model = getattr(event.result, "model", "unknown") if event.result else "unknown"
+    agent_name = getattr(event.result, "name", "default") if event.result else "default"
+    return {"Model": model, "AgentName": agent_name}
+
+agent = Agent(hooks=[
+    TokenUsageHook(
+        dimensions=[["Model", "AgentName"]],
+        dimension_resolver=resolve_dims,
+    )
+])
+```
+
+## Custom emitter
+
+By default the hook prints compact JSON to stdout, which the CloudWatch agent picks up. Replace the emitter when you need the payload to go somewhere else — for example, sending metrics to a non-CloudWatch backend or routing through your application's structured logging pipeline.
+
+```python
+import json
+import logging
+
+logger = logging.getLogger("token_metrics")
+
+def log_emitter(payload):
+    logger.info(json.dumps(payload))
+
+agent = Agent(hooks=[TokenUsageHook(emitter=log_emitter)])
+```
+
+You can also forward to an external service:
+
+```python
+import json
+import urllib.request
+
+def webhook_emitter(payload):
+    req = urllib.request.Request(
+        "https://metrics.example.com/ingest",
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    urllib.request.urlopen(req)
+
+agent = Agent(hooks=[TokenUsageHook(emitter=webhook_emitter)])
+```
+
+## Local development
+
+When you run an agent locally the default emitter prints one compact JSON line to
+stdout on every invocation. For example:
+
+```
+{"_aws":{"Timestamp":1700000000000,"CloudWatchMetrics":[...]},"inputTokens":42,...}
+```
+
+This is normal — it is CloudWatch Embedded Metric Format (EMF) output that the
+CloudWatch agent would consume in production. Locally there is no CloudWatch
+agent, so the lines simply appear in your console.
+
+### Suppressing output
+
+Pass a no-op emitter to silence the JSON lines entirely:
+
+```python
+from strands_token_telemetry import TokenUsageHook
+
+hook = TokenUsageHook(emitter=lambda payload: None)
+```
+
+### Human-readable output
+
+Pretty-print the payload so you can inspect it during development:
+
+```python
+import json
+from strands_token_telemetry import TokenUsageHook
+
+hook = TokenUsageHook(emitter=lambda p: print(json.dumps(p, indent=2)))
+```
+
+### Logging instead of stdout
+
+Route output through Python's `logging` module so it respects your existing log
+configuration:
+
+```python
+import json
+import logging
+from strands_token_telemetry import TokenUsageHook
+
+log = logging.getLogger("token_telemetry")
+
+hook = TokenUsageHook(emitter=lambda p: log.debug("%s", json.dumps(p)))
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```

strands_token_telemetry-0.1.0/README.md

@@ -0,0 +1,254 @@
+# strands-token-telemetry
+
+Emit [Strands Agents](https://github.com/strands-agents/sdk-python) token usage as [CloudWatch EMF](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) metrics.
+
+## Why this library?
+
+Strands Agents has built-in observability via OpenTelemetry traces, and AgentCore adds automatic CloudWatch metrics — but this turnkey telemetry only works when you use **BedrockModel** and deploy to **AgentCore**.
+
+If you're already on BedrockModel + AgentCore, you may not need this. Otherwise, this library fills three gaps:
+
+1. **Works with any model provider** — not locked into BedrockModel. Use Anthropic, LiteLLM, Ollama, or any Strands-compatible model and still get token metrics.
+
+2. **Works on any infrastructure** — ECS, Lambda, EC2, on-prem, or AgentCore. Anywhere the CloudWatch agent (or a compatible log sink) runs, you get first-class CloudWatch Metrics.
+
+3. **First-class CloudWatch Metrics, not trace attributes** — Strands' OTEL integration captures token counts as span attributes buried in traces. EMF creates real CloudWatch Metrics you can directly alarm on, dashboard, and apply metric math to (e.g. cost estimation). No OTEL collector setup or ADOT config required — just stdout.
+
+| | Strands OTEL traces | AgentCore auto-telemetry | This library |
+|---|---|---|---|
+| Any model provider | Yes | BedrockModel only | Yes |
+| Any deploy target | Yes | AgentCore only | Yes |
+| CloudWatch Metrics | No (span attributes) | Yes | Yes |
+| CloudWatch Alarms | No | Yes | Yes |
+| OTEL collector needed | Yes | Managed | No |
+| Setup | Configure ADOT/exporter | Deploy to AgentCore | One hook, one line |
+
+## Install
+
+```bash
+pip install strands-token-telemetry
+```
+
+`strands-agents` is a peer dependency — install it separately (or it's likely already in your project).
+
+## AI-assisted integration
+
+### For developers
+
+Copy and paste this prompt into Claude Code, Cursor, or your preferred AI coding
+assistant:
+
+> Install strands-token-telemetry and add a TokenUsageHook to my Strands agent.
+> Read the integration guide at
+> https://raw.githubusercontent.com/flockcover/strands-token-telemetry/main/docs/llms.txt
+> before writing any code.
+
+### For AI coding assistants
+
+If you are an AI coding assistant helping a developer integrate this library,
+fetch the full API reference and integration patterns from the LLM-optimized
+docs before generating code:
+
+    https://raw.githubusercontent.com/flockcover/strands-token-telemetry/main/docs/llms.txt
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_token_telemetry import TokenUsageHook
+
+agent = Agent(hooks=[TokenUsageHook()])
+```
+
+Every agent invocation prints a JSON line to stdout in [CloudWatch EMF](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) format. The CloudWatch agent picks this up and publishes metrics automatically.
+
+### Adding session context
+
+A common pattern is tagging metrics with a custom namespace plus user and session
+identifiers so you can filter and query them in CloudWatch Insights. Pass static
+dimension values for the model, and `extra_properties` for fields that should be
+searchable but not published as metric dimensions:
+
+```python
+from strands import Agent
+from strands_token_telemetry import TokenUsageHook
+
+hook = TokenUsageHook(
+    namespace="AcmeInc/StrandsTokens",
+    dimension_values={"Model": model_id},
+    extra_properties={"UserId": user_id, "SessionId": session_id},
+)
+agent = Agent(hooks=[hook])
+```
+
+`Model` appears as a CloudWatch Metric dimension you can alarm on, while `UserId`
+and `SessionId` stay as top-level properties queryable with CloudWatch Insights
+(e.g. `filter SessionId = "abc-123"`).
+
+Each invocation emits a single JSON line like this (pretty-printed here for
+readability):
+
+```json
+{
+  "_aws": {
+    "Timestamp": 1700000000000,
+    "CloudWatchMetrics": [
+      {
+        "Namespace": "AcmeInc/StrandsTokens",
+        "Dimensions": [["Model"]],
+        "Metrics": [
+          { "Name": "inputTokens", "Unit": "Count" },
+          { "Name": "outputTokens", "Unit": "Count" },
+          { "Name": "totalTokens", "Unit": "Count" },
+          { "Name": "cacheReadInputTokens", "Unit": "Count" },
+          { "Name": "cacheWriteInputTokens", "Unit": "Count" }
+        ]
+      }
+    ]
+  },
+  "Model": "us.anthropic.claude-sonnet-4-20250514",
+  "UserId": "user-42",
+  "SessionId": "abc-123",
+  "inputTokens": 1024,
+  "outputTokens": 256,
+  "totalTokens": 1280,
+  "cacheReadInputTokens": 512,
+  "cacheWriteInputTokens": 0
+}
+```
+
+## Configuration
+
+All constructor parameters are keyword-only.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `namespace` | `str` | `"Strands/AgentTokenUsage"` | CloudWatch metrics namespace |
+| `dimensions` | `list[list[str]]` | `[["Model"]]` | Dimension key sets |
+| `dimension_values` | `dict[str, str]` | `{}` | Static dimension key/value pairs |
+| `dimension_resolver` | `Callable` | `None` | Receives `AfterInvocationEvent`, returns dynamic dimension values |
+| `extra_properties` | `dict[str, Any]` | `None` | Extra top-level properties (searchable in CloudWatch Insights) |
+| `emitter` | `Callable` | `default_emitter` | Function that receives the payload dict |
+
+## Dynamic dimensions
+
+Use `dimension_resolver` when a dimension value isn't known until the agent runs — for example, the model name returned by the provider, or an agent identifier pulled from the event. Static values like environment or service name can go in `dimension_values`; the resolver handles everything that changes per invocation.
+
+```python
+def resolve_dims(event):
+    model = getattr(event.result, "model", "unknown") if event.result else "unknown"
+    return {"Model": model}
+
+agent = Agent(hooks=[
+    TokenUsageHook(
+        dimensions=[["Model", "Environment"]],
+        dimension_values={"Environment": "prod"},
+        dimension_resolver=resolve_dims,
+    )
+])
+```
+
+A more advanced example — splitting metrics by both model and a per-request agent name:
+
+```python
+def resolve_dims(event):
+    model = getattr(event.result, "model", "unknown") if event.result else "unknown"
+    agent_name = getattr(event.result, "name", "default") if event.result else "default"
+    return {"Model": model, "AgentName": agent_name}
+
+agent = Agent(hooks=[
+    TokenUsageHook(
+        dimensions=[["Model", "AgentName"]],
+        dimension_resolver=resolve_dims,
+    )
+])
+```
+
+## Custom emitter
+
+By default the hook prints compact JSON to stdout, which the CloudWatch agent picks up. Replace the emitter when you need the payload to go somewhere else — for example, sending metrics to a non-CloudWatch backend or routing through your application's structured logging pipeline.
+
+```python
+import json
+import logging
+
+logger = logging.getLogger("token_metrics")
+
+def log_emitter(payload):
+    logger.info(json.dumps(payload))
+
+agent = Agent(hooks=[TokenUsageHook(emitter=log_emitter)])
+```
+
+You can also forward to an external service:
+
+```python
+import json
+import urllib.request
+
+def webhook_emitter(payload):
+    req = urllib.request.Request(
+        "https://metrics.example.com/ingest",
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    urllib.request.urlopen(req)
+
+agent = Agent(hooks=[TokenUsageHook(emitter=webhook_emitter)])
+```
+
+## Local development
+
+When you run an agent locally the default emitter prints one compact JSON line to
+stdout on every invocation. For example:
+
+```
+{"_aws":{"Timestamp":1700000000000,"CloudWatchMetrics":[...]},"inputTokens":42,...}
+```
+
+This is normal — it is CloudWatch Embedded Metric Format (EMF) output that the
+CloudWatch agent would consume in production. Locally there is no CloudWatch
+agent, so the lines simply appear in your console.
+
+### Suppressing output
+
+Pass a no-op emitter to silence the JSON lines entirely:
+
+```python
+from strands_token_telemetry import TokenUsageHook
+
+hook = TokenUsageHook(emitter=lambda payload: None)
+```
+
+### Human-readable output
+
+Pretty-print the payload so you can inspect it during development:
+
+```python
+import json
+from strands_token_telemetry import TokenUsageHook
+
+hook = TokenUsageHook(emitter=lambda p: print(json.dumps(p, indent=2)))
+```
+
+### Logging instead of stdout
+
+Route output through Python's `logging` module so it respects your existing log
+configuration:
+
+```python
+import json
+import logging
+from strands_token_telemetry import TokenUsageHook
+
+log = logging.getLogger("token_telemetry")
+
+hook = TokenUsageHook(emitter=lambda p: log.debug("%s", json.dumps(p)))
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```

strands_token_telemetry-0.1.0/docs/PUBLISHING.md

@@ -0,0 +1,125 @@
+# Publishing to PyPI
+
+This project is published to PyPI automatically via GitHub Actions using [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/). No API tokens or passwords are stored in the repository.
+
+## How it works
+
+The workflow at `.github/workflows/publish.yml` runs whenever a GitHub Release is published. It:
+
+1. Runs the test suite (`pytest -v`)
+2. Builds the package (`python -m build`, producing sdist and wheel)
+3. Publishes to PyPI using OIDC identity tokens
+
+PyPI verifies that the upload request came from an authorized GitHub Actions workflow in this repository, with no shared secrets involved.
+
+## Initial setup
+
+### 1. Create the GitHub environment
+
+1. Go to **Settings > Environments** in the GitHub repository
+2. Click **New environment**
+3. Name it `pypi` (must match the `environment:` value in the workflow)
+4. Optionally add protection rules (e.g. required reviewers) to gate releases
+
+### 2. Register the trusted publisher on PyPI
+
+If the project does not yet exist on PyPI, use "pending publisher" to claim the name:
+
+1. Log in to [pypi.org](https://pypi.org)
+2. Go to your account's [Publishing](https://pypi.org/manage/account/publishing/) page
+3. Under **Add a new pending publisher**, fill in:
+   - **PyPI project name**: `strands-token-telemetry`
+   - **Owner**: `flockcover`
+   - **Repository**: `strands-token-telemetry`
+   - **Workflow name**: `publish.yml`
+   - **Environment name**: `pypi`
+4. Click **Add**
+
+If the project already exists on PyPI:
+
+1. Go to the project's [manage page](https://pypi.org/manage/project/strands-token-telemetry/settings/publishing/)
+2. Under **Add a new publisher**, fill in the same values as above
+
+## Triggering a release
+
+### 1. Bump the version
+
+Update the `version` field in `pyproject.toml`:
+
+```toml
+[project]
+version = "0.2.0"
+```
+
+Commit and push to `main`.
+
+### 2. Create a GitHub Release
+
+1. Go to **Releases** in the GitHub repository
+2. Click **Draft a new release**
+3. Click **Choose a tag** and type the new version prefixed with `v` (e.g. `v0.2.0`), then select **Create new tag on publish**
+4. Set the release title (e.g. `v0.2.0`)
+5. Write release notes (or click **Generate release notes** to auto-fill from merged PRs)
+6. Click **Publish release**
+
+This triggers the workflow. Monitor progress in the **Actions** tab.
+
+### Using the GitHub CLI
+
+```bash
+# create a tag and release in one step
+gh release create v0.2.0 --title "v0.2.0" --generate-notes
+```
+
+## Maintaining the OIDC connection
+
+### What can break
+
+The trusted publisher configuration on PyPI must match the workflow exactly. A publish will fail if any of these change without updating PyPI:
+
+| Field | Must match |
+|---|---|
+| Owner | `flockcover` (GitHub org) |
+| Repository | `strands-token-telemetry` |
+| Workflow name | `publish.yml` (filename, not the `name:` field inside it) |
+| Environment name | `pypi` |
+
+### If the workflow file is renamed
+
+1. Rename the file in the repository
+2. On PyPI, remove the old publisher and add a new one with the updated workflow name
+
+### If the repository is transferred or renamed
+
+1. On PyPI, remove the old publisher
+2. Add a new publisher with the updated owner/repository values
+
+### If the GitHub environment is renamed
+
+1. Update the `environment:` value in the workflow to match the new name
+2. On PyPI, remove the old publisher and add a new one with the new environment name
+
+### Verifying the connection
+
+After any changes, create a pre-release to test:
+
+```bash
+gh release create v0.2.0-rc.1 --title "v0.2.0-rc.1" --prerelease --generate-notes
+```
+
+Check the Actions tab for the workflow run. If the publish step fails with a "trusted publisher not found" error, compare the values in the error message against your PyPI publisher configuration.
+
+### Revoking access
+
+To stop the workflow from publishing:
+
+1. On PyPI, go to the project's publishing settings and remove the trusted publisher
+2. Optionally delete the `pypi` environment in GitHub repo settings
+
+## Troubleshooting
+
+**"Trusted publisher not found"** -- The publisher fields on PyPI don't match the workflow. Double-check owner, repository, workflow filename, and environment name.
+
+**"Version already exists"** -- PyPI does not allow overwriting a published version. Bump the version in `pyproject.toml` and create a new release.
+
+**Tests fail and publish is skipped** -- The `publish` job depends on `test`. Fix the failing tests, then create a new release (or re-run the failed workflow from the Actions tab after the fix is on `main`).

strands_token_telemetry-0.1.0/docs/llms.txt

@@ -0,0 +1,146 @@
+# strands-token-telemetry
+
+> Emit Strands Agents token usage as CloudWatch Embedded Metric Format (EMF) metrics.
+
+## Install
+
+pip install strands-token-telemetry
+
+strands-agents is a peer dependency (>= 0.1.0).
+
+## Public API
+
+The package exports three names from strands_token_telemetry:
+
+- TokenUsageHook — the main hook class (HookProvider)
+- build_emf_payload — pure function to build an EMF dict
+- default_emitter — prints compact JSON to stdout
+
+## TokenUsageHook
+
+A Strands HookProvider. Pass it in the hooks list when creating an Agent.
+
+Constructor (all parameters are keyword-only):
+
+  namespace: str = "Strands/AgentTokenUsage"
+      CloudWatch metrics namespace.
+
+  dimensions: list[list[str]] = [["Model"]]
+      Dimension key sets for CloudWatch metrics.
+
+  dimension_values: dict[str, str] = {}
+      Static dimension key/value pairs. Keys must appear in dimensions.
+
+  dimension_resolver: Callable[[AfterInvocationEvent], dict[str, str]] | None = None
+      Called on each invocation with the event. Returns dimension key/value
+      pairs that are merged with dimension_values (resolver wins on conflict).
+      Use this when a value isn't known until runtime (e.g. model name from
+      the provider response).
+
+  extra_properties: dict[str, Any] | None = None
+      Additional top-level properties in the EMF payload. These are NOT
+      published as CloudWatch Metric dimensions but ARE queryable in
+      CloudWatch Logs Insights. Use for user IDs, session IDs, trace IDs, etc.
+
+  emitter: Callable[[dict[str, Any]], None] = default_emitter
+      Function that receives the final payload dict. Override to route output
+      to logging, a webhook, or /dev/null.
+
+## Minimal usage
+
+from strands import Agent
+from strands_token_telemetry import TokenUsageHook
+
+agent = Agent(hooks=[TokenUsageHook()])
+
+## Common patterns
+
+### Custom namespace with session context
+
+hook = TokenUsageHook(
+    namespace="AcmeInc/StrandsTokens",
+    dimension_values={"Model": model_id},
+    extra_properties={"UserId": user_id, "SessionId": session_id},
+)
+agent = Agent(hooks=[hook])
+
+### Dynamic dimensions resolved at runtime
+
+def resolve_dims(event):
+    model = getattr(event.result, "model", "unknown") if event.result else "unknown"
+    return {"Model": model}
+
+agent = Agent(hooks=[
+    TokenUsageHook(
+        dimensions=[["Model", "Environment"]],
+        dimension_values={"Environment": "prod"},
+        dimension_resolver=resolve_dims,
+    )
+])
+
+### Suppress stdout output (local development)
+
+hook = TokenUsageHook(emitter=lambda payload: None)
+
+### Pretty-print for debugging
+
+import json
+hook = TokenUsageHook(emitter=lambda p: print(json.dumps(p, indent=2)))
+
+### Route to Python logging
+
+import json, logging
+log = logging.getLogger("token_telemetry")
+hook = TokenUsageHook(emitter=lambda p: log.debug("%s", json.dumps(p)))
+
+### Forward to an external service
+
+import json, urllib.request
+
+def webhook_emitter(payload):
+    req = urllib.request.Request(
+        "https://metrics.example.com/ingest",
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    urllib.request.urlopen(req)
+
+hook = TokenUsageHook(emitter=webhook_emitter)
+
+## build_emf_payload
+
+Pure function — useful if you want to build the EMF dict without the hook.
+
+build_emf_payload(
+    usage: dict[str, int],        # token counters (each becomes a metric)
+    namespace: str,
+    dimensions: list[list[str]],
+    dimension_values: dict[str, str],
+    extra_properties: dict[str, Any] | None = None,
+    timestamp_ms: int | None = None,  # defaults to now
+) -> dict[str, Any]
+
+## Metrics emitted
+
+The hook emits every key present in the SDK's usage dict as a Count metric.
+Typical keys: inputTokens, outputTokens, totalTokens, cacheReadInputTokens,
+cacheWriteInputTokens.
+
+## Key concepts
+
+- dimension_values vs extra_properties: dimension_values become CloudWatch
+  Metric dimensions (you can alarm/filter on them). extra_properties are
+  top-level JSON fields queryable in CloudWatch Logs Insights but not
+  published as metric dimensions.
+
+- dimension_resolver vs dimension_values: use dimension_values for values
+  known at hook construction time (environment, service name). Use
+  dimension_resolver for values only available at invocation time (model
+  name from the response, agent name).
+
+- emitter: the default prints compact JSON to stdout for the CloudWatch
+  agent. Override it to send elsewhere or suppress output.
+
+## Source
+
+https://github.com/flockcover/strands-token-telemetry

strands_token_telemetry-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strands-token-telemetry"
+version = "0.1.0"
+description = "Emit Strands agent token usage as CloudWatch EMF metrics"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Tom Harvey", email = "tom.harvey@flockcover.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+    "strands-agents>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/flockcover/strands-token-telemetry"
+Issues = "https://github.com/flockcover/strands-token-telemetry/issues"
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

strands_token_telemetry-0.1.0/src/strands_token_telemetry/__init__.py

@@ -0,0 +1,8 @@
+"""strands-token-telemetry — emit Strands agent token usage as CloudWatch EMF metrics."""
+
+__version__ = "0.1.0"
+
+from strands_token_telemetry.emf import build_emf_payload
+from strands_token_telemetry.hook import TokenUsageHook, default_emitter
+
+__all__ = ["TokenUsageHook", "build_emf_payload", "default_emitter"]

strands_token_telemetry-0.1.0/src/strands_token_telemetry/emf.py

@@ -0,0 +1,59 @@
+"""Pure function to build CloudWatch EMF (Embedded Metric Format) payloads."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+def build_emf_payload(
+    *,
+    usage: dict[str, int],
+    namespace: str,
+    dimensions: list[list[str]],
+    dimension_values: dict[str, str],
+    extra_properties: dict[str, Any] | None = None,
+    timestamp_ms: int | None = None,
+) -> dict[str, Any]:
+    """Build a CloudWatch EMF structured-log payload.
+
+    Args:
+        usage: Token usage counters — each key becomes a metric with Unit="Count".
+        namespace: CloudWatch metrics namespace.
+        dimensions: Dimension key sets (e.g. [["Model"], ["Model", "Agent"]]).
+        dimension_values: Concrete dimension key/value pairs emitted as top-level properties.
+        extra_properties: Additional top-level properties (searchable in CloudWatch Insights
+            but not published as metrics).
+        timestamp_ms: Epoch milliseconds for the metric datum. Defaults to now.
+
+    Returns:
+        A dict ready to be serialised as JSON and printed to stdout for the CloudWatch agent.
+    """
+    if timestamp_ms is None:
+        timestamp_ms = int(time.time() * 1000)
+
+    metrics = [{"Name": key, "Unit": "Count"} for key in usage]
+
+    payload: dict[str, Any] = {
+        "_aws": {
+            "Timestamp": timestamp_ms,
+            "CloudWatchMetrics": [
+                {
+                    "Namespace": namespace,
+                    "Dimensions": dimensions,
+                    "Metrics": metrics,
+                }
+            ],
+        },
+    }
+
+    # Dimension values must be top-level properties (EMF spec).
+    payload.update(dimension_values)
+
+    # Metric values must also be top-level.
+    payload.update(usage)
+
+    if extra_properties:
+        payload.update(extra_properties)
+
+    return payload

strands_token_telemetry-0.1.0/src/strands_token_telemetry/hook.py

@@ -0,0 +1,108 @@
+"""TokenUsageHook — a Strands HookProvider that emits token usage as CloudWatch EMF logs."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any, Callable
+
+from strands_token_telemetry.emf import build_emf_payload
+
+if TYPE_CHECKING:
+    from strands.hooks.events import AfterInvocationEvent
+    from strands.hooks.registry import HookRegistry
+
+logger = logging.getLogger(__name__)
+
+Emitter = Callable[[dict[str, Any]], None]
+
+
+def default_emitter(payload: dict[str, Any]) -> None:
+    """Print compact JSON to stdout (picked up by the CloudWatch agent)."""
+    print(json.dumps(payload, separators=(",", ":")))
+
+
+class TokenUsageHook:
+    """HookProvider that emits token-usage metrics in CloudWatch EMF format.
+
+    Usage::
+
+        from strands import Agent
+        from strands_token_telemetry import TokenUsageHook
+
+        agent = Agent(hooks=[TokenUsageHook(namespace="MyApp/Tokens")])
+    """
+
+    def __init__(
+        self,
+        *,
+        namespace: str = "Strands/AgentTokenUsage",
+        dimensions: list[list[str]] | None = None,
+        dimension_values: dict[str, str] | None = None,
+        dimension_resolver: Callable[[AfterInvocationEvent], dict[str, str]] | None = None,
+        extra_properties: dict[str, Any] | None = None,
+        emitter: Emitter | None = None,
+    ) -> None:
+        self.namespace = namespace
+        self.dimensions = dimensions if dimensions is not None else [["Model"]]
+        self.dimension_values = dimension_values or {}
+        self.dimension_resolver = dimension_resolver
+        self.extra_properties = extra_properties
+        self.emitter = emitter or default_emitter
+
+    # -- HookProvider protocol --------------------------------------------------
+
+    def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
+        from strands.hooks.events import AfterInvocationEvent
+
+        registry.add_callback(AfterInvocationEvent, self._on_after_invocation)
+
+    # -- internals --------------------------------------------------------------
+
+    @staticmethod
+    def _extract_usage(event: AfterInvocationEvent) -> dict[str, int] | None:
+        """Return token-usage dict from *event*, or ``None`` if unavailable."""
+        if event.result is None:
+            return None
+
+        # Primary path: event.result.metrics.accumulated_usage (newer SDK)
+        try:
+            usage = event.result.metrics.accumulated_usage
+            if usage:
+                return dict(usage)
+        except AttributeError:
+            pass
+
+        # Fallback: agent-level metrics (older SDK / original code path)
+        try:
+            invocations = event.agent.event_loop_metrics.agent_invocations
+            if invocations:
+                usage = invocations[-1].usage
+                if usage:
+                    return dict(usage)
+        except AttributeError:
+            pass
+
+        return None
+
+    def _on_after_invocation(self, event: AfterInvocationEvent) -> None:
+        try:
+            usage = self._extract_usage(event)
+            if not usage:
+                return
+
+            dim_values = dict(self.dimension_values)
+            if self.dimension_resolver is not None:
+                dim_values.update(self.dimension_resolver(event))
+
+            payload = build_emf_payload(
+                usage=usage,
+                namespace=self.namespace,
+                dimensions=self.dimensions,
+                dimension_values=dim_values,
+                extra_properties=self.extra_properties,
+            )
+
+            self.emitter(payload)
+        except Exception:
+            logger.exception("TokenUsageHook: failed to emit token-usage metrics")

strands_token_telemetry-0.1.0/tests/test_emf.py

@@ -0,0 +1,92 @@
+"""Pure unit tests for build_emf_payload — no mocks required."""
+
+from strands_token_telemetry.emf import build_emf_payload
+
+
+FIXED_TS = 1_700_000_000_000
+
+
+def _make_payload(**overrides):
+    defaults = dict(
+        usage={"inputTokens": 100, "outputTokens": 50, "totalTokens": 150},
+        namespace="Test/NS",
+        dimensions=[["Model"]],
+        dimension_values={"Model": "test-model"},
+        timestamp_ms=FIXED_TS,
+    )
+    defaults.update(overrides)
+    return build_emf_payload(**defaults)
+
+
+class TestPayloadStructure:
+    def test_aws_block_present(self):
+        payload = _make_payload()
+        assert "_aws" in payload
+        assert "Timestamp" in payload["_aws"]
+        assert "CloudWatchMetrics" in payload["_aws"]
+
+    def test_namespace_set(self):
+        payload = _make_payload()
+        cw = payload["_aws"]["CloudWatchMetrics"][0]
+        assert cw["Namespace"] == "Test/NS"
+
+    def test_timestamp_forwarded(self):
+        payload = _make_payload()
+        assert payload["_aws"]["Timestamp"] == FIXED_TS
+
+    def test_default_timestamp_generated(self):
+        payload = _make_payload(timestamp_ms=None)
+        ts = payload["_aws"]["Timestamp"]
+        # Should be a recent epoch-ms value (sanity check: after 2024-01-01).
+        assert ts > 1_704_067_200_000
+
+
+class TestMetrics:
+    def test_metric_names_match_usage_keys(self):
+        usage = {"inputTokens": 10, "outputTokens": 20, "totalTokens": 30}
+        payload = _make_payload(usage=usage)
+        metric_names = {m["Name"] for m in payload["_aws"]["CloudWatchMetrics"][0]["Metrics"]}
+        assert metric_names == set(usage.keys())
+
+    def test_all_units_are_count(self):
+        payload = _make_payload()
+        for m in payload["_aws"]["CloudWatchMetrics"][0]["Metrics"]:
+            assert m["Unit"] == "Count"
+
+    def test_metric_values_top_level(self):
+        usage = {"inputTokens": 10, "outputTokens": 20, "totalTokens": 30}
+        payload = _make_payload(usage=usage)
+        for key, value in usage.items():
+            assert payload[key] == value
+
+
+class TestDimensions:
+    def test_single_dimension_set(self):
+        payload = _make_payload(dimensions=[["Model"]])
+        assert payload["_aws"]["CloudWatchMetrics"][0]["Dimensions"] == [["Model"]]
+
+    def test_multiple_dimension_sets(self):
+        dims = [["Model"], ["Model", "Agent"]]
+        payload = _make_payload(dimensions=dims)
+        assert payload["_aws"]["CloudWatchMetrics"][0]["Dimensions"] == dims
+
+    def test_dimension_values_top_level(self):
+        payload = _make_payload(dimension_values={"Model": "gpt-4", "Agent": "bot"})
+        assert payload["Model"] == "gpt-4"
+        assert payload["Agent"] == "bot"
+
+
+class TestExtraProperties:
+    def test_extra_properties_included(self):
+        payload = _make_payload(extra_properties={"requestId": "abc-123"})
+        assert payload["requestId"] == "abc-123"
+
+    def test_extra_properties_not_in_metrics(self):
+        payload = _make_payload(extra_properties={"requestId": "abc-123"})
+        metric_names = {m["Name"] for m in payload["_aws"]["CloudWatchMetrics"][0]["Metrics"]}
+        assert "requestId" not in metric_names
+
+    def test_none_extra_properties_ok(self):
+        payload = _make_payload(extra_properties=None)
+        # Should just not blow up; no extra keys beyond usage + dimensions + _aws.
+        assert "_aws" in payload

strands_token_telemetry-0.1.0/tests/test_hook.py

@@ -0,0 +1,139 @@
+"""Tests for TokenUsageHook — mocks Strands types."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock
+
+from strands_token_telemetry.hook import TokenUsageHook, default_emitter
+
+
+def _make_event(usage=None, *, result_none=False):
+    """Build a minimal mock AfterInvocationEvent."""
+    event = MagicMock()
+    if result_none:
+        event.result = None
+        return event
+    event.result.metrics.accumulated_usage = usage or {
+        "inputTokens": 100,
+        "outputTokens": 50,
+        "totalTokens": 150,
+    }
+    return event
+
+
+class TestEmitterCalled:
+    def test_emitter_receives_valid_payload(self):
+        emitter = MagicMock()
+        hook = TokenUsageHook(emitter=emitter)
+        event = _make_event()
+
+        hook._on_after_invocation(event)
+
+        emitter.assert_called_once()
+        payload = emitter.call_args[0][0]
+        assert "_aws" in payload
+        assert payload["inputTokens"] == 100
+
+    def test_no_emission_when_result_is_none(self):
+        emitter = MagicMock()
+        hook = TokenUsageHook(emitter=emitter)
+        event = _make_event(result_none=True)
+
+        hook._on_after_invocation(event)
+
+        emitter.assert_not_called()
+
+
+class TestConfiguration:
+    def test_custom_namespace(self):
+        emitter = MagicMock()
+        hook = TokenUsageHook(namespace="Custom/NS", emitter=emitter)
+        hook._on_after_invocation(_make_event())
+
+        payload = emitter.call_args[0][0]
+        assert payload["_aws"]["CloudWatchMetrics"][0]["Namespace"] == "Custom/NS"
+
+    def test_custom_dimensions(self):
+        emitter = MagicMock()
+        dims = [["Model", "Agent"]]
+        hook = TokenUsageHook(dimensions=dims, emitter=emitter)
+        hook._on_after_invocation(_make_event())
+
+        payload = emitter.call_args[0][0]
+        assert payload["_aws"]["CloudWatchMetrics"][0]["Dimensions"] == dims
+
+    def test_static_dimension_values(self):
+        emitter = MagicMock()
+        hook = TokenUsageHook(
+            dimension_values={"Model": "claude-sonnet"},
+            emitter=emitter,
+        )
+        hook._on_after_invocation(_make_event())
+
+        payload = emitter.call_args[0][0]
+        assert payload["Model"] == "claude-sonnet"
+
+    def test_dimension_resolver_called_and_merged(self):
+        emitter = MagicMock()
+        resolver = MagicMock(return_value={"Model": "resolved-model", "Region": "us-east-1"})
+        hook = TokenUsageHook(
+            dimension_values={"Model": "static-model"},
+            dimension_resolver=resolver,
+            emitter=emitter,
+        )
+        event = _make_event()
+        hook._on_after_invocation(event)
+
+        resolver.assert_called_once_with(event)
+        payload = emitter.call_args[0][0]
+        # Resolver values override static ones.
+        assert payload["Model"] == "resolved-model"
+        assert payload["Region"] == "us-east-1"
+
+    def test_extra_properties_forwarded(self):
+        emitter = MagicMock()
+        hook = TokenUsageHook(
+            extra_properties={"requestId": "req-42"},
+            emitter=emitter,
+        )
+        hook._on_after_invocation(_make_event())
+
+        payload = emitter.call_args[0][0]
+        assert payload["requestId"] == "req-42"
+
+
+class TestDefaultEmitter:
+    def test_prints_compact_json(self, capsys):
+        payload = {"key": "value", "num": 1}
+        default_emitter(payload)
+
+        captured = capsys.readouterr()
+        assert captured.out.strip() == json.dumps(payload, separators=(",", ":"))
+
+
+class TestRegisterHooks:
+    def test_registers_after_invocation_callback(self):
+        from strands_token_telemetry.hook import TokenUsageHook
+
+        hook = TokenUsageHook()
+        registry = MagicMock()
+
+        hook.register_hooks(registry)
+
+        registry.add_callback.assert_called_once()
+        # First arg should be the AfterInvocationEvent class.
+        from strands.hooks.events import AfterInvocationEvent
+
+        event_type = registry.add_callback.call_args[0][0]
+        assert event_type is AfterInvocationEvent
+
+
+class TestExceptionHandling:
+    def test_emitter_exception_is_caught(self):
+        def bad_emitter(payload):
+            raise RuntimeError("boom")
+
+        hook = TokenUsageHook(emitter=bad_emitter)
+        # Should not raise.
+        hook._on_after_invocation(_make_event())

strands_token_telemetry-0.1.0/tests/test_init.py

@@ -0,0 +1,11 @@
+from strands_token_telemetry import TokenUsageHook, build_emf_payload, default_emitter, __version__
+
+
+def test_version():
+    assert __version__ == "0.1.0"
+
+
+def test_public_exports():
+    assert callable(TokenUsageHook)
+    assert callable(build_emf_payload)
+    assert callable(default_emitter)