rootmark 0.1.1__tar.gz → 0.1.2__tar.gz

{rootmark-0.1.1 → rootmark-0.1.2}/CHANGELOG.md

@@ -3,6 +3,60 @@
 Notable changes to the `rootmark` SDK. Versions follow the collector's own
 releases loosely; where the two must match, it says so.
 
+## 0.1.2
+
+**Fixes a defect in 0.1.1 that stopped runs ever completing.** Upgrade from
+0.1.1; there is no reason to stay on it.
+
+### Fixed
+
+- **A discarded span held its run open for ever.** 0.1.1 made `start_span`
+  write a provisional row, but `discard_span` still emitted nothing -- correct
+  when a discarded span had never been mentioned, wrong once it had. The
+  provisional row said `running` and nothing superseded it, and a run is
+  finished only when all of its spans are. Every run containing a discarded
+  span therefore stayed in progress permanently.
+
+  It was not a corner case. The boto3 interceptor discards its span on *every*
+  Bedrock call made inside a Strands agent, because the Strands patch is
+  already tracing the same call. On the first deployment running both, 18 of
+  18 runs recorded after the upgrade were stuck "running" and none could ever
+  complete.
+
+  Two changes, because one of them is a guarantee and the other is the right
+  shape:
+
+  * `discard_span` now **retracts** a span it announced, writing a terminal
+    `cancelled` row at the end sentinel. Any caller that announced a span can
+    discard it without stranding it. `cancelled` rather than `success`,
+    because nothing was measured -- a 0 ms success would be averaged in as a
+    real and very fast call -- and it is not an error, so error rates are
+    untouched.
+  * `start_span` takes `announce=False` for a span opened speculatively, and
+    the boto3 interceptor uses it. A span that may turn out to belong to
+    another layer is no longer announced at open, so discarding it costs
+    nothing and leaves no `cancelled` row on every trace.
+
+  The cost of the second change: a bare Bedrock call made through boto3
+  *outside* a Strands agent is no longer visible while it runs, only once it
+  completes. Inside Strands -- the common case, and the one that was broken --
+  the agent span above it keeps in-progress visibility.
+
+### Repairing existing data
+
+Runs already stuck cannot fix themselves: their provisional rows will never be
+superseded. Write the retraction the fixed code would have written -- a
+`cancelled` row at `row_version` 2147483647 with the same `(project_id,
+trace_id, start_time, span_id)` -- for every span matching
+
+```sql
+SELECT * FROM trace_events FINAL
+WHERE status NOT IN ('success','error','timeout','cancelled')
+```
+
+then re-project the affected runs. On the deployment above this moved 18 runs
+from `running` to `success` and left no open spans.
+
 ## 0.1.1
 
 **Upgrading from 0.1.0 requires a collector upgrade first.** See *Compatibility*

{rootmark-0.1.1 → rootmark-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootmark
-Version: 0.1.1
+Version: 0.1.2
 Summary: Rootmark SDK -- agent instrumentation
 Project-URL: Homepage, https://rootmark.dev
 Project-URL: Documentation, https://rootmark.dev/docs/
@@ -59,6 +59,11 @@ Requires Python 3.12 or newer.
 > Upgrade the collector first (it needs ClickHouse migrations `007`–`009`), or
 > stay on 0.1.0.
 
+> **0.1.1 is broken; use 0.1.2 or later.** In 0.1.1 a span that the SDK opened
+> and then discarded was left looking like it was still running, which held its
+> whole run open permanently. Any Bedrock call made through boto3 inside a
+> Strands agent hits it, on every call.
+
 ## What changed in 0.1.1
 
 - **Runs are visible while they are still going.** A span is recorded when it

{rootmark-0.1.1 → rootmark-0.1.2}/README.md

@@ -21,6 +21,11 @@ Requires Python 3.12 or newer.
 > Upgrade the collector first (it needs ClickHouse migrations `007`–`009`), or
 > stay on 0.1.0.
 
+> **0.1.1 is broken; use 0.1.2 or later.** In 0.1.1 a span that the SDK opened
+> and then discarded was left looking like it was still running, which held its
+> whole run open permanently. Any Bedrock call made through boto3 inside a
+> Strands agent hits it, on every call.
+
 ## What changed in 0.1.1
 
 - **Runs are visible while they are still going.** A span is recorded when it

{rootmark-0.1.1 → rootmark-0.1.2}/pyproject.toml

@@ -1,58 +1,58 @@
-[project]
-name = "rootmark"
-version = "0.1.1"
-description = "Rootmark SDK -- agent instrumentation"
-readme = "README.md"
-requires-python = ">=3.12"
-# No licence declared as of 0.1.1; to be added in a later release. Without
-# one the package defaults to all rights reserved -- see the 0.1.0 release
-# commit (329e16c) for the reasoning and why it still needs revisiting.
-keywords = ["agents", "observability", "tracing", "llm", "instrumentation"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Programming Language :: Python :: 3.14",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Topic :: System :: Monitoring",
-    "Typing :: Typed",
-]
-dependencies = [
-    "pydantic>=2.10.0",
-    "httpx>=0.28.0",
-]
-
-[project.urls]
-Homepage = "https://rootmark.dev"
-Documentation = "https://rootmark.dev/docs/"
-Source = "https://github.com/IvanAdactic/rootmark"
-
-[project.optional-dependencies]
-# OpenAI integration (Group 4); tested with 1.x and 2.x
-openai = ["openai>=1.40.0,<3"]
-# LangChain callback handler (D4.7); BaseCallbackHandler is stable across 0.3.x and 1.x
-langchain = ["langchain-core>=0.3,<2"]
-# CrewAI event listeners (D5.6); BaseEventListener + crewai_event_bus (tested 0.86–1.x)
-crewai = ["crewai>=0.86,<2"]
-# Strands SDK / AWS Bedrock agent patch (D6.1)
-strands = ["strands-agents>=1.26.0"]
-# Boto3 / botocore interceptor for Bedrock zero-code-change path (D6.3)
-boto3 = ["boto3>=1.35.0"]
-dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "openai>=1.40.0,<3", "langchain-core>=0.3,<2", "crewai>=0.86,<2"]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/rootmark"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-pythonpath = ["src"]
-markers = [
-    "integration: needs docker-compose (API, worker, ClickHouse, Postgres)",
-]
-
+[project]
+name = "rootmark"
+version = "0.1.2"
+description = "Rootmark SDK -- agent instrumentation"
+readme = "README.md"
+requires-python = ">=3.12"
+# No licence declared as of 0.1.2; to be added in a later release. Without
+# one the package defaults to all rights reserved -- see the 0.1.0 release
+# commit (329e16c) for the reasoning and why it still needs revisiting.
+keywords = ["agents", "observability", "tracing", "llm", "instrumentation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.10.0",
+    "httpx>=0.28.0",
+]
+
+[project.urls]
+Homepage = "https://rootmark.dev"
+Documentation = "https://rootmark.dev/docs/"
+Source = "https://github.com/IvanAdactic/rootmark"
+
+[project.optional-dependencies]
+# OpenAI integration (Group 4); tested with 1.x and 2.x
+openai = ["openai>=1.40.0,<3"]
+# LangChain callback handler (D4.7); BaseCallbackHandler is stable across 0.3.x and 1.x
+langchain = ["langchain-core>=0.3,<2"]
+# CrewAI event listeners (D5.6); BaseEventListener + crewai_event_bus (tested 0.86–1.x)
+crewai = ["crewai>=0.86,<2"]
+# Strands SDK / AWS Bedrock agent patch (D6.1)
+strands = ["strands-agents>=1.26.0"]
+# Boto3 / botocore interceptor for Bedrock zero-code-change path (D6.3)
+boto3 = ["boto3>=1.35.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "openai>=1.40.0,<3", "langchain-core>=0.3,<2", "crewai>=0.86,<2"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rootmark"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "integration: needs docker-compose (API, worker, ClickHouse, Postgres)",
+]
+