otelstarter 0.1.0__tar.gz

otelstarter-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Built binaries
+/otelstarter
+/dist/
+
+# Python
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Python build output
+dist/
+build/

otelstarter-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

otelstarter-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: otelstarter
+Version: 0.1.0
+Summary: Business-aware domain events for OpenTelemetry, from the otelstarter project.
+Project-URL: Homepage, https://github.com/IvyMurage/otelstarter
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.45.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: opentelemetry-sdk==1.45.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# otelstarter (Python)
+
+Business-aware domain events for OpenTelemetry. Part of [otelstarter](https://github.com/IvyMurage/otelstarter).
+
+```python
+from otelstarter import observability
+
+observability.event(
+    "payment.completed",
+    domain="payments",
+    operation="payment",
+    outcome="success",
+    entity_type="payment",
+    entity_id=payment.id,
+)
+```
+
+Each call emits **one OpenTelemetry log-based event**: a log record whose event name is `payment.completed`, linked to the current trace. OpenTelemetry adds the trace and span IDs, service name and environment itself.
+
+## Install
+
+The package is not on PyPI yet. Install it from GitHub:
+
+```bash
+pip install "otelstarter @ git+https://github.com/IvyMurage/otelstarter#subdirectory=sdk/python"
+```
+
+It depends only on `opentelemetry-api`. Run your app with OpenTelemetry configured (for example via `otelstarter run -- <your command>`), or `event()` quietly does nothing.
+
+## Rules it enforces
+
+- **Business meaning, not payloads.** Only the named fields above exist, with values that are short strings or ints. Anything else is left out with a warning.
+- **`<domain>.<action>` names**, in lowercase, such as `order.created` or `payment.authorization.failed`. A name that breaks the rule is still recorded, with a one-time `OtelStarterWarning`.
+- **Never breaks your app.** `event()` never raises. Internal errors become a one-time `OtelStarterWarning`.
+- **One signal per event.** No duplicate span event or log line, and no automatic metric, so `entity_id` never becomes a metric label.
+
+## Finding events in Grafana
+
+With `otelstarter run`, open Grafana → Explore → Loki:
+
+```text
+{service_name="shop"} |= "payment."                       # all payment events
+{service_name="shop"} | event_domain="payments"           # by domain
+{service_name="shop"} | event_outcome="failure"           # failures only
+```
+
+Each event carries `trace_id`, so you can jump from it to the request's trace in Tempo. Loki does not store OpenTelemetry's event-name field, which is why the event name is also the log body.
+
+See [docs/DOMAIN_EVENTS.md](https://github.com/IvyMurage/otelstarter/blob/main/docs/DOMAIN_EVENTS.md) for the event model.
+
+## Development
+
+```bash
+cd sdk/python
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check . && ruff format --check .
+mypy
+```

otelstarter-0.1.0/README.md

@@ -0,0 +1,60 @@
+# otelstarter (Python)
+
+Business-aware domain events for OpenTelemetry. Part of [otelstarter](https://github.com/IvyMurage/otelstarter).
+
+```python
+from otelstarter import observability
+
+observability.event(
+    "payment.completed",
+    domain="payments",
+    operation="payment",
+    outcome="success",
+    entity_type="payment",
+    entity_id=payment.id,
+)
+```
+
+Each call emits **one OpenTelemetry log-based event**: a log record whose event name is `payment.completed`, linked to the current trace. OpenTelemetry adds the trace and span IDs, service name and environment itself.
+
+## Install
+
+The package is not on PyPI yet. Install it from GitHub:
+
+```bash
+pip install "otelstarter @ git+https://github.com/IvyMurage/otelstarter#subdirectory=sdk/python"
+```
+
+It depends only on `opentelemetry-api`. Run your app with OpenTelemetry configured (for example via `otelstarter run -- <your command>`), or `event()` quietly does nothing.
+
+## Rules it enforces
+
+- **Business meaning, not payloads.** Only the named fields above exist, with values that are short strings or ints. Anything else is left out with a warning.
+- **`<domain>.<action>` names**, in lowercase, such as `order.created` or `payment.authorization.failed`. A name that breaks the rule is still recorded, with a one-time `OtelStarterWarning`.
+- **Never breaks your app.** `event()` never raises. Internal errors become a one-time `OtelStarterWarning`.
+- **One signal per event.** No duplicate span event or log line, and no automatic metric, so `entity_id` never becomes a metric label.
+
+## Finding events in Grafana
+
+With `otelstarter run`, open Grafana → Explore → Loki:
+
+```text
+{service_name="shop"} |= "payment."                       # all payment events
+{service_name="shop"} | event_domain="payments"           # by domain
+{service_name="shop"} | event_outcome="failure"           # failures only
+```
+
+Each event carries `trace_id`, so you can jump from it to the request's trace in Tempo. Loki does not store OpenTelemetry's event-name field, which is why the event name is also the log body.
+
+See [docs/DOMAIN_EVENTS.md](https://github.com/IvyMurage/otelstarter/blob/main/docs/DOMAIN_EVENTS.md) for the event model.
+
+## Development
+
+```bash
+cd sdk/python
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check . && ruff format --check .
+mypy
+```

otelstarter-0.1.0/RELEASING.md

@@ -0,0 +1,44 @@
+# Releasing the Python SDK
+
+The `Release Python SDK` workflow (`.github/workflows/release-python-sdk.yml`) publishes `sdk/python` to PyPI when a tag like `sdk-python-v0.1.0` is pushed. It uses PyPI **Trusted Publishing**: PyPI trusts the workflow's GitHub identity, so no API token is stored anywhere.
+
+## One-time setup
+
+**On PyPI**, signed in as the maintainer:
+
+1. Open your account menu, then **Publishing**.
+2. Add a new **pending publisher** for **GitHub Actions** with:
+
+   | Field | Value |
+   |-------|-------|
+   | PyPI project name | `otelstarter` |
+   | Repository | `IvyMurage/otelstarter` |
+   | Workflow file name | `release-python-sdk.yml` |
+   | Environment name | `pypi` |
+
+A pending publisher does not reserve the name. If someone else registers `otelstarter` before the first release, the pending publisher stops working, so publish soon after setting it up.
+
+**On GitHub**, in the repository's **Settings → Environments**:
+
+1. Create an environment named `pypi`.
+2. Optionally add yourself as a **required reviewer**. Every release then waits for you to click *Approve* before anything is uploaded.
+
+## Each release
+
+1. Set the new version in `src/otelstarter/__init__.py`. It is the only place the version lives.
+2. Add the release to `CHANGELOG.md`.
+3. Merge to `main`, then tag that commit and push the tag:
+
+   ```bash
+   git tag sdk-python-v0.1.0
+   git push origin sdk-python-v0.1.0
+   ```
+
+The workflow then:
+
+1. checks that the tag matches the version, and stops if it doesn't
+2. runs the tests
+3. builds and checks the package
+4. publishes it
+
+A version cannot be uploaded to PyPI twice, so a mistake needs a new version number.

otelstarter-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "otelstarter"
+dynamic = ["version"] # read from src/otelstarter/__init__.py, the single source
+description = "Business-aware domain events for OpenTelemetry, from the otelstarter project."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+# Only the API: an app without OpenTelemetry configured gets a no-op, and the
+# app chooses the SDK version. 1.45.0 is the version otelstarter tests with.
+dependencies = ["opentelemetry-api>=1.45.0"]
+
+[project.optional-dependencies]
+dev = [
+    "opentelemetry-sdk==1.45.0",
+    "pytest>=8",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[project.urls]
+Homepage = "https://github.com/IvyMurage/otelstarter"
+
+[tool.hatch.version]
+path = "src/otelstarter/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/otelstarter"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "BLE"]
+
+[tool.mypy]
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]  # unexpected warnings fail the tests

otelstarter-0.1.0/src/otelstarter/__init__.py

@@ -0,0 +1,11 @@
+"""otelstarter: business-aware domain events on top of OpenTelemetry.
+
+from otelstarter import observability
+
+observability.event("order.created", domain="orders", outcome="success")
+"""
+
+from otelstarter import observability
+
+__all__ = ["observability"]
+__version__ = "0.1.0"

otelstarter-0.1.0/src/otelstarter/observability.py

@@ -0,0 +1,144 @@
+"""Record business events alongside your app's OpenTelemetry telemetry.
+
+    from otelstarter import observability
+
+    observability.event("payment.completed", domain="payments", outcome="success")
+
+Each call emits one OpenTelemetry log-based event: a log record whose event
+name is the event, linked to the current trace. OpenTelemetry adds the
+technical context (trace and span IDs, service name, environment) itself.
+
+Recording an event never raises, so observability can never break the app.
+Problems are reported once each through Python's warnings module.
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+
+from opentelemetry._logs import SeverityNumber, get_logger
+
+__all__ = ["OtelStarterWarning", "event"]
+
+# <domain>.<action>, lowercase: "payment.completed", "payment.authorization.failed".
+_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")
+
+# Longer values look like payloads, not business meaning.
+_MAX_VALUE_LENGTH = 256
+
+# A proxy logger: it starts sending once the app configures OpenTelemetry
+# (for example via opentelemetry-instrument) and does nothing before that.
+_logger = get_logger("otelstarter")
+
+_warned: set[str] = set()
+
+
+class OtelStarterWarning(UserWarning):
+    """Warns about a domain event that was recorded imperfectly or not at all.
+
+    Filter it like any warning, for example to fail tests on it:
+    ``warnings.simplefilter("error", OtelStarterWarning)``.
+    """
+
+
+def event(
+    name: str,
+    *,
+    domain: str | None = None,
+    operation: str | None = None,
+    outcome: str | None = None,
+    entity_type: str | None = None,
+    entity_id: str | int | None = None,
+) -> None:
+    """Record that something meaningful happened in the business.
+
+    Args:
+        name: What happened, as ``<domain>.<action>``, for example
+            ``"payment.completed"``. The only required argument.
+        domain: The business capability, for example ``"payments"``.
+        operation: The business activity, for example ``"payment"``.
+        outcome: Preferably ``"success"``, ``"failure"``, ``"cancelled"``
+            or ``"rejected"``.
+        entity_type: The business object involved, for example ``"order"``.
+        entity_id: Its identifier. Recorded on the event only; otelstarter
+            never turns it into a metric label.
+
+    There is deliberately no way to attach other data: events carry business
+    meaning, not business payloads.
+    """
+    try:
+        _emit(name, domain, operation, outcome, entity_type, entity_id)
+    except Exception as exc:  # noqa: BLE001 - recording must never break the app
+        _warn_once("emit-failed", f"otelstarter could not record event {name!r}: {exc!r}")
+
+
+def _emit(
+    name: object,
+    domain: object,
+    operation: object,
+    outcome: object,
+    entity_type: object,
+    entity_id: object,
+) -> None:
+    if not isinstance(name, str) or not name:
+        _warn_once("name-type", f"Event name must be a non-empty string, got {name!r}. The event was not recorded.")
+        return
+    if not _NAME_PATTERN.match(name):
+        _warn_once(
+            "name:" + name,
+            f"Event name {name!r} does not follow <domain>.<action> in lowercase, "
+            "for example 'payment.completed'. The event was still recorded.",
+        )
+
+    fields = {
+        "event.domain": domain,
+        "event.outcome": outcome,
+        "business.operation": operation,
+        "business.entity.type": entity_type,
+        "business.entity.id": entity_id,
+    }
+    attributes: dict[str, str] = {}
+    for key, value in fields.items():
+        cleaned = _clean(name, key, value)
+        if cleaned is not None:
+            attributes[key] = cleaned
+
+    _logger.emit(
+        event_name=name,
+        body=name,  # so log views that show only the body still show the event
+        severity_number=SeverityNumber.INFO,
+        severity_text="INFO",
+        attributes=attributes,
+    )
+
+
+def _clean(name: str, key: str, value: object) -> str | None:
+    """Return the value as a short string, or None to leave the field out."""
+    if value is None:
+        return None
+    # bool is a subclass of int, so rule it out explicitly.
+    if isinstance(value, bool) or not isinstance(value, (str, int)):
+        _warn_once(
+            f"type:{key}",
+            f"{key} on event {name!r} must be a string or int, got {type(value).__name__}. "
+            "It was left out: events carry business meaning, not payloads.",
+        )
+        return None
+    text = str(value)
+    if len(text) > _MAX_VALUE_LENGTH:
+        _warn_once(
+            f"long:{key}",
+            f"{key} on event {name!r} is {len(text)} characters long, which looks like a payload. "
+            f"It was cut to {_MAX_VALUE_LENGTH}.",
+        )
+        text = text[:_MAX_VALUE_LENGTH]
+    return text
+
+
+def _warn_once(key: str, message: str) -> None:
+    if key in _warned:
+        return
+    _warned.add(key)
+    # stacklevel=4 points the warning at the user's event() call.
+    warnings.warn(message, OtelStarterWarning, stacklevel=4)

otelstarter-0.1.0/tests/conftest.py

@@ -0,0 +1,46 @@
+"""Configure an in-memory OpenTelemetry SDK once for the whole test run.
+
+OpenTelemetry allows the global providers to be set only once per process,
+so each test clears the exporters instead of creating new providers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from opentelemetry import trace
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter, SimpleLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from otelstarter import observability
+
+RESOURCE = Resource.create({"service.name": "shop", "deployment.environment.name": "test"})
+
+_logs = InMemoryLogRecordExporter()
+_log_provider = LoggerProvider(resource=RESOURCE)
+_log_provider.add_log_record_processor(SimpleLogRecordProcessor(_logs))
+set_logger_provider(_log_provider)
+
+_spans = InMemorySpanExporter()
+_tracer_provider = TracerProvider(resource=RESOURCE)
+_tracer_provider.add_span_processor(SimpleSpanProcessor(_spans))
+trace.set_tracer_provider(_tracer_provider)
+
+
+@pytest.fixture
+def logs() -> Iterator[InMemoryLogRecordExporter]:
+    _logs.clear()
+    observability._warned.clear()  # each test sees warnings afresh
+    yield _logs
+
+
+@pytest.fixture
+def spans() -> Iterator[InMemorySpanExporter]:
+    _spans.clear()
+    yield _spans

otelstarter-0.1.0/tests/test_observability.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+import warnings
+
+import pytest
+from opentelemetry import trace
+from opentelemetry._logs import SeverityNumber
+from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from otelstarter import observability
+from otelstarter.observability import OtelStarterWarning
+
+
+def only_record(logs: InMemoryLogRecordExporter):  # type: ignore[no-untyped-def]
+    finished = logs.get_finished_logs()
+    assert len(finished) == 1, f"want exactly one log record, got {len(finished)}"
+    return finished[0]
+
+
+def test_event_is_one_named_log_record(logs: InMemoryLogRecordExporter) -> None:
+    observability.event(
+        "payment.completed",
+        domain="payments",
+        operation="payment",
+        outcome="success",
+        entity_type="payment",
+        entity_id="pay_123",
+    )
+
+    readable = only_record(logs)
+    record = readable.log_record
+    assert record.event_name == "payment.completed"
+    assert record.body == "payment.completed"
+    assert record.severity_number == SeverityNumber.INFO
+    assert dict(record.attributes or {}) == {
+        "event.domain": "payments",
+        "event.outcome": "success",
+        "business.operation": "payment",
+        "business.entity.type": "payment",
+        "business.entity.id": "pay_123",
+    }
+    # Technical context comes from OpenTelemetry's resource, not the caller.
+    assert readable.resource.attributes["service.name"] == "shop"
+    assert readable.resource.attributes["deployment.environment.name"] == "test"
+
+
+def test_only_the_name_is_required(logs: InMemoryLogRecordExporter) -> None:
+    observability.event("order.created")
+
+    record = only_record(logs).log_record
+    assert record.event_name == "order.created"
+    assert dict(record.attributes or {}) == {}
+
+
+def test_event_is_linked_to_the_active_span(logs: InMemoryLogRecordExporter, spans: InMemorySpanExporter) -> None:
+    tracer = trace.get_tracer("test")
+    with tracer.start_as_current_span("POST /payments") as span:
+        observability.event("payment.completed", outcome="success")
+
+    record = only_record(logs).log_record
+    assert record.trace_id == span.get_span_context().trace_id
+    assert record.span_id == span.get_span_context().span_id
+    # One signal only: no duplicate span event (DOMAIN_EVENTS section 13).
+    (finished,) = spans.get_finished_spans()
+    assert finished.events == ()
+
+
+def test_integer_entity_id_is_recorded_as_text(logs: InMemoryLogRecordExporter) -> None:
+    observability.event("loan.submitted", entity_id=42)
+
+    assert only_record(logs).log_record.attributes == {"business.entity.id": "42"}
+
+
+def test_badly_named_event_warns_once_and_is_still_recorded(logs: InMemoryLogRecordExporter) -> None:
+    with pytest.warns(OtelStarterWarning, match="<domain>.<action>"):
+        observability.event("paymentDone")
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")  # a second warning would fail here
+        observability.event("paymentDone")
+
+    assert [r.log_record.event_name for r in logs.get_finished_logs()] == ["paymentDone", "paymentDone"]
+
+
+@pytest.mark.parametrize("name", ["", None, 123])
+def test_unusable_name_is_skipped_with_a_warning(logs: InMemoryLogRecordExporter, name: object) -> None:
+    with pytest.warns(OtelStarterWarning, match="non-empty string"):
+        observability.event(name)  # type: ignore[arg-type]
+
+    assert logs.get_finished_logs() == ()
+
+
+def test_payload_values_are_kept_out(logs: InMemoryLogRecordExporter) -> None:
+    with pytest.warns(OtelStarterWarning, match="must be a string or int"):
+        observability.event("order.created", entity_id={"card": "4111 1111 1111 1111"})  # type: ignore[arg-type]
+
+    assert "business.entity.id" not in (only_record(logs).log_record.attributes or {})
+
+
+def test_long_values_are_cut(logs: InMemoryLogRecordExporter) -> None:
+    with pytest.warns(OtelStarterWarning, match="looks like a payload"):
+        observability.event("order.created", operation="x" * 1000)
+
+    assert len((only_record(logs).log_record.attributes or {})["business.operation"]) == 256
+
+
+def test_no_catch_all_argument_exists() -> None:
+    # Events carry business meaning, not payloads: arbitrary fields are a
+    # programming error that type checkers and Python itself reject.
+    with pytest.raises(TypeError):
+        observability.event("order.created", body={"items": []})  # type: ignore[call-arg]
+
+
+def test_internal_failure_never_reaches_the_app(
+    logs: InMemoryLogRecordExporter, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    def broken_emit(*args: object, **kwargs: object) -> None:
+        raise RuntimeError("exporter exploded")
+
+    monkeypatch.setattr(observability._logger, "emit", broken_emit)
+
+    with pytest.warns(OtelStarterWarning, match="could not record event"):
+        observability.event("payment.completed")  # must not raise
+
+
+def test_works_without_opentelemetry_configured() -> None:
+    # A fresh interpreter has no SDK configured: event() must be a quiet no-op.
+    result = subprocess.run(
+        [sys.executable, "-W", "error", "-c", "from otelstarter import observability; observability.event('a.b')"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr