jps-observability-utils 0.1.0__tar.gz

jps_observability_utils-0.1.0/LICENSE

@@ -0,0 +1,14 @@
+MIT License
+
+Copyright (c) 2025 Jaideep Sundaram
+
+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 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.

jps_observability_utils-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: jps-observability-utils
+Version: 0.1.0
+Summary: Utilities for auditing Python and Node.js repositories for observability-related instrumentation and integrations.
+Author-email: Jaideep Sundaram <jai.python3@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jai-python3/jps-observability-utils
+Project-URL: Repository, https://github.com/jai-python3/jps-observability-utils
+Project-URL: Issues, https://github.com/jai-python3/jps-observability-utils/issues
+Keywords: cookiecutter,bootstrap,project-generator,automation
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.3
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: isort>=5.13.0; extra == "dev"
+Requires-Dist: codecov>=2.1.13; extra == "dev"
+Requires-Dist: autoflake>=2.3.1; extra == "dev"
+Requires-Dist: pre-commit>=3.8.0; extra == "dev"
+Requires-Dist: bandit>=1.7.9; extra == "dev"
+Requires-Dist: vulture>=2.11; extra == "dev"
+Requires-Dist: flynt>=1.0.1; extra == "dev"
+Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
+Requires-Dist: darglint>=1.8.1; extra == "dev"
+Requires-Dist: mypy>=1.12.1; extra == "dev"
+Requires-Dist: bump-my-version>=1.0.1; extra == "dev"
+Requires-Dist: git-changelog>=2.7.0; extra == "dev"
+Dynamic: license-file
+
+# jps-observability-utils
+
+Utilities for auditing Python and Node.js repositories for evidence of observability-related instrumentation, telemetry configuration, monitoring components, and integrations with common observability platforms.
+
+## Overview
+
+`jps-observability-utils` is a Python CLI package that performs static repository scans and generates observability audit reports.
+
+The initial version is designed for legacy codebase assessment, onboarding, and engineering due diligence. It helps identify evidence of technologies such as OpenTelemetry, Prometheus, Datadog, New Relic, Sentry, Elastic APM, collector configuration, metrics endpoints, and structured logging patterns.
+
+The package is intentionally evidence-based. It does not claim runtime certainty. It reports what the repository contents suggest.
+
+## Initial Scope
+
+The initial release includes two Typer-based CLI commands:
+
+- `audit-python` — scan a Python repository
+- `audit-node` — scan a Node.js repository
+
+Each command generates a human-readable Markdown report and a machine-readable JSON report.
+
+## What the Tool Detects
+
+The scanners look for evidence of observability-related instrumentation and integrations, including:
+
+- telemetry instrumentation libraries
+- OpenTelemetry SDKs, exporters, and environment variables
+- Prometheus client libraries and `/metrics` patterns
+- vendor-specific observability platforms such as Datadog, New Relic, Sentry, and Elastic APM
+- collector / exporter configuration
+- deployment and environment configuration relevant to telemetry
+- structured logging patterns relevant to observability
+
+## What the Tool Does Not Do
+
+This project does not, in its initial version:
+
+- execute code
+- validate runtime telemetry emission
+- prove that observability is functioning in production
+- modify the target repository
+- auto-remediate missing instrumentation
+
+## Why This Tool Exists
+
+Legacy repositories often contain partial, inconsistent, or undocumented observability setups. Engineers reviewing a codebase typically need fast answers to questions such as:
+
+- Does this project appear to use OpenTelemetry?
+- Is Prometheus instrumentation present?
+- Is there evidence of Datadog or New Relic integration?
+- Are telemetry environment variables configured?
+- Is there collector or OTLP configuration in the repo?
+- Are there signs of structured logging or metrics endpoints?
+
+This tool is intended to reduce manual grep-heavy investigation.
+
+## Proposed CLI Usage
+
+Examples:
+
+```bash
+jps-observability-utils audit-python /path/to/python-repo --format both --output-dir ./reports
+jps-observability-utils audit-node /path/to/node-repo --format both --output-dir ./reports
+```
+
+Possible options may include:
+
+- `--output-dir`
+- `--format [md|json|both]`
+- `--ignore PATTERN`
+- `--verbose`
+
+## Expected Report Content
+
+Each report should include:
+
+- scan metadata
+- repository path
+- number of files scanned
+- summary of detected technologies
+- findings grouped by category
+- confidence level for each finding
+- file paths and evidence locations
+- caveats explaining that the audit is static and heuristic-based
+
+## Confidence Model
+
+A simple confidence model is recommended:
+
+- **High** — strong evidence such as dependency + initialization code or env vars + exporter configuration
+- **Medium** — partial but meaningful evidence such as dependency presence without clear initialization
+- **Low** — weak or indirect evidence only
+
+## Suggested MVP Detection Targets
+
+### Python repositories
+
+- OpenTelemetry
+- Prometheus
+- Datadog
+- New Relic
+- Sentry
+- Elastic APM
+- collector / OTLP config
+- structured logging indicators
+
+### Node.js repositories
+
+- OpenTelemetry
+- Prometheus
+- Datadog
+- New Relic
+- Sentry
+- Elastic APM
+- collector / OTLP config
+- structured logging indicators
+
+## Recommended Package Structure
+
+```text
+src/jps_observability_utils/
+├── cli.py
+├── constants.py
+├── models.py
+├── scanner.py
+├── report_writer.py
+├── matchers/
+│   ├── common.py
+│   ├── python_repo.py
+│   └── node_repo.py
+└── utils/
+    ├── file_utils.py
+    └── text_utils.py
+```
+
+## Design Principles
+
+- static evidence detection, not runtime proof
+- clear and conservative language
+- modular detection rules
+- stable JSON output
+- easy extensibility for additional technologies and languages
+
+## Example GitHub Project Description
+
+Utilities for auditing Python and Node.js repositories for observability-related instrumentation and integrations.
+
+## Development Notes
+
+Recommended implementation choices:
+
+- Python 3.11+
+- Typer for CLI
+- pathlib for filesystem traversal
+- dataclasses or Pydantic for report models
+- pytest for testing
+
+## Testing Strategy
+
+The test suite should include small fixture repositories representing:
+
+- positive OpenTelemetry detection
+- Prometheus-only detection
+- vendor-specific APM detection
+- no observability evidence
+- mixed evidence across code and deployment files
+
+## Future Enhancements
+
+Potential future additions:
+
+- unified `audit-repo` command with language auto-detection
+- HTML reports
+- SARIF output
+- maturity scoring
+- custom rule packs
+- support for additional languages
+
+## Status
+
+This repository is intended to start with two focused audit utilities and expand over time as the detection catalog matures.
+

jps_observability_utils-0.1.0/README.md

@@ -0,0 +1,182 @@
+# jps-observability-utils
+
+Utilities for auditing Python and Node.js repositories for evidence of observability-related instrumentation, telemetry configuration, monitoring components, and integrations with common observability platforms.
+
+## Overview
+
+`jps-observability-utils` is a Python CLI package that performs static repository scans and generates observability audit reports.
+
+The initial version is designed for legacy codebase assessment, onboarding, and engineering due diligence. It helps identify evidence of technologies such as OpenTelemetry, Prometheus, Datadog, New Relic, Sentry, Elastic APM, collector configuration, metrics endpoints, and structured logging patterns.
+
+The package is intentionally evidence-based. It does not claim runtime certainty. It reports what the repository contents suggest.
+
+## Initial Scope
+
+The initial release includes two Typer-based CLI commands:
+
+- `audit-python` — scan a Python repository
+- `audit-node` — scan a Node.js repository
+
+Each command generates a human-readable Markdown report and a machine-readable JSON report.
+
+## What the Tool Detects
+
+The scanners look for evidence of observability-related instrumentation and integrations, including:
+
+- telemetry instrumentation libraries
+- OpenTelemetry SDKs, exporters, and environment variables
+- Prometheus client libraries and `/metrics` patterns
+- vendor-specific observability platforms such as Datadog, New Relic, Sentry, and Elastic APM
+- collector / exporter configuration
+- deployment and environment configuration relevant to telemetry
+- structured logging patterns relevant to observability
+
+## What the Tool Does Not Do
+
+This project does not, in its initial version:
+
+- execute code
+- validate runtime telemetry emission
+- prove that observability is functioning in production
+- modify the target repository
+- auto-remediate missing instrumentation
+
+## Why This Tool Exists
+
+Legacy repositories often contain partial, inconsistent, or undocumented observability setups. Engineers reviewing a codebase typically need fast answers to questions such as:
+
+- Does this project appear to use OpenTelemetry?
+- Is Prometheus instrumentation present?
+- Is there evidence of Datadog or New Relic integration?
+- Are telemetry environment variables configured?
+- Is there collector or OTLP configuration in the repo?
+- Are there signs of structured logging or metrics endpoints?
+
+This tool is intended to reduce manual grep-heavy investigation.
+
+## Proposed CLI Usage
+
+Examples:
+
+```bash
+jps-observability-utils audit-python /path/to/python-repo --format both --output-dir ./reports
+jps-observability-utils audit-node /path/to/node-repo --format both --output-dir ./reports
+```
+
+Possible options may include:
+
+- `--output-dir`
+- `--format [md|json|both]`
+- `--ignore PATTERN`
+- `--verbose`
+
+## Expected Report Content
+
+Each report should include:
+
+- scan metadata
+- repository path
+- number of files scanned
+- summary of detected technologies
+- findings grouped by category
+- confidence level for each finding
+- file paths and evidence locations
+- caveats explaining that the audit is static and heuristic-based
+
+## Confidence Model
+
+A simple confidence model is recommended:
+
+- **High** — strong evidence such as dependency + initialization code or env vars + exporter configuration
+- **Medium** — partial but meaningful evidence such as dependency presence without clear initialization
+- **Low** — weak or indirect evidence only
+
+## Suggested MVP Detection Targets
+
+### Python repositories
+
+- OpenTelemetry
+- Prometheus
+- Datadog
+- New Relic
+- Sentry
+- Elastic APM
+- collector / OTLP config
+- structured logging indicators
+
+### Node.js repositories
+
+- OpenTelemetry
+- Prometheus
+- Datadog
+- New Relic
+- Sentry
+- Elastic APM
+- collector / OTLP config
+- structured logging indicators
+
+## Recommended Package Structure
+
+```text
+src/jps_observability_utils/
+├── cli.py
+├── constants.py
+├── models.py
+├── scanner.py
+├── report_writer.py
+├── matchers/
+│   ├── common.py
+│   ├── python_repo.py
+│   └── node_repo.py
+└── utils/
+    ├── file_utils.py
+    └── text_utils.py
+```
+
+## Design Principles
+
+- static evidence detection, not runtime proof
+- clear and conservative language
+- modular detection rules
+- stable JSON output
+- easy extensibility for additional technologies and languages
+
+## Example GitHub Project Description
+
+Utilities for auditing Python and Node.js repositories for observability-related instrumentation and integrations.
+
+## Development Notes
+
+Recommended implementation choices:
+
+- Python 3.11+
+- Typer for CLI
+- pathlib for filesystem traversal
+- dataclasses or Pydantic for report models
+- pytest for testing
+
+## Testing Strategy
+
+The test suite should include small fixture repositories representing:
+
+- positive OpenTelemetry detection
+- Prometheus-only detection
+- vendor-specific APM detection
+- no observability evidence
+- mixed evidence across code and deployment files
+
+## Future Enhancements
+
+Potential future additions:
+
+- unified `audit-repo` command with language auto-detection
+- HTML reports
+- SARIF output
+- maturity scoring
+- custom rule packs
+- support for additional languages
+
+## Status
+
+This repository is intended to start with two focused audit utilities and expand over time as the detection catalog matures.
+

jps_observability_utils-0.1.0/pyproject.toml

@@ -0,0 +1,210 @@
+[build-system]
+requires = ["setuptools>=68", "wheel", "build"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jps-observability-utils"
+version = "0.1.0"
+description = "Utilities for auditing Python and Node.js repositories for observability-related instrumentation and integrations."
+readme = "README.md"
+authors = [{ name = "Jaideep Sundaram", email = "jai.python3@gmail.com" }]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["cookiecutter", "bootstrap", "project-generator", "automation"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+dependencies = [
+    "typer>=0.12.3"
+]
+
+[project.urls]
+Homepage = "https://github.com/jai-python3/jps-observability-utils"
+Repository = "https://github.com/jai-python3/jps-observability-utils"
+Issues = "https://github.com/jai-python3/jps-observability-utils/issues"
+
+[project.scripts]
+jps-observability-utils = "jps_observability_utils.cli:app"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0.0"]
+dev = [
+    "flake8>=7.0.0",
+    "black>=24.0.0",
+    "build>=1.2.1",
+    "twine>=5.0.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "isort>=5.13.0",
+    "codecov>=2.1.13",
+    "autoflake>=2.3.1",
+    "pre-commit>=3.8.0",
+    "bandit>=1.7.9",
+    "vulture>=2.11",
+    "flynt>=1.0.1",
+    "pydocstyle>=6.3.0",
+    "darglint>=1.8.1",
+    "mypy>=1.12.1",
+    "bump-my-version>=1.0.1",
+    "git-changelog>=2.7.0",
+
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = false
+
+# -----------------------------
+# Formatting Tools
+# -----------------------------
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+src_paths = ["src", "tests"]
+
+# -----------------------------
+# Testing & Coverage
+# -----------------------------
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-v --disable-warnings"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+# -----------------------------
+# Type Checking
+# -----------------------------
+[tool.mypy]
+python_version = "3.12"
+
+# --- Strictness for production code ---
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+ignore_missing_imports = true
+strict_optional = true
+warn_unused_ignores = true
+warn_unreachable = true
+warn_return_any = true
+show_error_codes = true
+
+# --- Paths to exclude from main analysis ---
+exclude = [
+    "build/",
+    "dist/",
+]
+
+# --- Override: Relax typing rules for test modules ---
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+check_untyped_defs = false
+ignore_missing_imports = true
+
+# -----------------------------
+# Linting
+# -----------------------------
+[tool.flake8]
+max-line-length = 120
+
+# E203: Black disagrees with slice whitespace rules
+# W503: Black prefers line breaks before binary operators
+# W292: Black intentionally removes trailing newline at EOF (Black behavior)
+extend-ignore = ["E203", "W503", "W292"]
+
+exclude = [
+    ".git",
+    "__pycache__",
+    "build",
+    "dist",
+    "venv",
+    ".venv",
+    ".tox",
+    ".pytest_cache",
+    "docs"
+]
+
+# -----------------------------
+# Security (Bandit)
+# -----------------------------
+[tool.bandit]
+# Rules intentionally skipped because they are either safe in this context or false positives.
+# Skipped rules:
+#   B101 - assert_used: Safe since assertions are not used for security enforcement.
+#   B110 - try_except_pass: Handled via code review standards instead.
+#   B404 - import_subprocess: subprocess used safely for CLI operations (no user input).
+#   B603 - subprocess_without_shell_equals_true: All subprocess calls use shell=False.
+#   B607 - start_process_with_partial_path: Safe usage of 'gh' (GitHub CLI) in developer tools.
+#   B108 - hardcoded_tmp_directory: Acceptable since temp dirs are user- and timestamp-specific.
+
+skips = ["B101", "B110", "B404", "B603", "B607", "B108"]
+
+# Bandit target directories (recursive)
+targets = ["src"]
+recursive = true
+
+# Exclude test code from Bandit scans
+exclude = ["tests"]
+
+# -----------------------------
+# Docstring Style Checkers
+# -----------------------------
+[tool.pydocstyle]
+convention = "google"
+add-ignore = [
+    "D107",  # Missing docstring in __init__
+    "D203",  # 1 blank line required before class docstring
+]
+match-dir = "src"
+
+[tool.darglint]
+docstring_style = "google"
+strictness = "short"
+ignore_regex = "(^test_)"
+message_template = "{path}:{line}: {msg_id} {msg}"
+
+# -----------------------------------------------------------
+# bump-my-version for manual version bumps
+# -----------------------------------------------------------
+[tool.bumpversion]
+current_version = "0.1.0"   # optional but nice to have in one place
+commit = true
+tag = true
+tag_name = "v{new_version}"
+message = "chore(release): bump version to v{new_version} [skip ci]"
+hooks = true
+
+
+[[tool.bumpversion.files]]
+filename = ".version"                     # plain text file with just the version
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "src/jps_observability_utils/__init__.py"   # change if your package name differs
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'
+
+[tool.git-changelog]
+template = "keepachangelog"   # produces beautiful Keep a Changelog format
+output = "CHANGELOG.md"

jps_observability_utils-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jps_observability_utils-0.1.0/src/jps_observability_utils/__init__.py

@@ -0,0 +1,3 @@
+"""jps_observability_utils package."""
+
+__version__ = "0.1.0"