Metadata-Version: 2.4
Name: jps-observability-utils
Version: 0.2.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.

