update readme

Author: guenp

README.md

@@ -1,59 +1,117 @@
 # Telemetric
 
 [![Actions Status][actions-badge]][actions-link]
-[![Documentation Status][rtd-badge]][rtd-link]
-
 [![PyPI version][pypi-version]][pypi-link]
-[![Conda-Forge][conda-badge]][conda-link]
-[![PyPI platforms][pypi-platforms]][pypi-link]
-
-[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
 
 <!-- SPHINX-START -->
 
 <!-- prettier-ignore-start -->
 [actions-badge]:            https://github.com/scientific-python/telemetric/workflows/CI/badge.svg
 [actions-link]:             https://github.com/scientific-python/telemetric/actions
-[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/telemetric
-[conda-link]:               https://github.com/conda-forge/telemetric-feedstock
-[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
-[github-discussions-link]:  https://github.com/scientific-python/telemetric/discussions
 [pypi-link]:                https://pypi.org/project/telemetric/
-[pypi-platforms]:           https://img.shields.io/pypi/pyversions/telemetric
 [pypi-version]:             https://img.shields.io/pypi/v/telemetric
-[rtd-badge]:                https://readthedocs.org/projects/telemetric/badge/?version=latest
-[rtd-link]:                 https://telemetric.readthedocs.io/en/latest/?badge=latest
 
 <!-- prettier-ignore-end -->
 
-This library adds basic telemetry to Python projects that traces the usage and
-run time of Python functions within a given scope.
+This library provides lightweight telemetry for Python projects, collecting
+statistics on function parameter usage to understand how APIs are being used.
 
 ## Installation
 
-Prerequisites:
-
-```
-pip install opentelemetry-distro
-pip install opentelemetry-exporter-otlp
-opentelemetry-bootstrap --action=install
+```bash
+pip install telemetric
 ```
 
 ## Usage
 
-To track usage of one or more existing Python projects, run:
+### Automatic Function Wrapping
+
+To automatically track parameter usage statistics for existing Python packages,
+use the `install()` function before importing the target modules:
 
 ```python
-from opentelemetry.instrumentation.auto_instrumentation import initialize
 from telemetric import install
 
-install([my_project.my_module])
-initialize()
-start_span_processor("my-project-service")
+# Install telemetry for specific modules
+install(["scipy.stats._correlation", "scipy.stats._distn_infrastructure"])
+
+from scipy import stats
+
+# Use functions normally
+stats.norm.pdf(x=1, loc=1, scale=0.01)
+stats.norm(loc=1, scale=0.02).pdf(1)
+
+# Retrieve statistics for wrapped functions
+print("Call counts:", stats.norm.pdf._get_counts())
+print("Parameter stats:", stats.norm.pdf._get_param_stats())
+```
+
+The `_get_counts()` method returns a tuple of:
+
+- Total function calls
+- Number of calls that raised errors
+- Number of calls with invalid arguments (wrapping issues)
+
+The `_get_param_stats()` method returns detailed statistics for each parameter:
+
+- Parameter name (or None for positional-only)
+- Number of times the parameter was passed
+- Tracked parameter values (if specified)
+- Counts for each tracked value (if specified)
+
+### Manual Function Decoration
+
+For more control, use the `stats_deco_auto` decorator to automatically track all
+parameters:
+
+```python
+from telemetric import stats_deco_auto
+
+
+@stats_deco_auto
+def my_function(x, y=10, z="default"):
+    return x + y
+
+
+my_function(5)
+my_function(5, y=20)
+my_function(5, 20, "custom")
+
+print(my_function._get_counts())
+print(my_function._get_param_stats())
+```
+
+For fine-grained control over which parameter values to track, use `stats_deco`:
+
+```python
+from telemetric import stats_deco
+
+
+@stats_deco(x=None, y=(10, 20, 30), z=("default", "custom"))
+def my_function(x, y=10, z="default"):
+    return x + y
+
+
+# The decorator will track:
+# - Whether x was passed (any value)
+# - How often y was 10, 20, or 30 (and count other values separately)
+# - How often z was "default" or "custom" (and count other values separately)
+```
+
+### Printing All Statistics
+
+To print a summary of all wrapped functions and their statistics:
+
+```python
+from telemetric.statswrapper import print_all_stats
+
+# After your code has run
+print_all_stats()
 ```
 
-To explicitly add instrumentation to functions you want to trace, use the `span`
-decorator:
+### OpenTelemetry Integration (Legacy)
+
+The library also supports OpenTelemetry-based tracing for distributed systems:
 
 ```python
 from telemetric import span, start_span_processor
@@ -69,16 +127,21 @@ if __name__ == "__main__":
     foo(bar="baz")
 ```
 
-## Start collector
+## OpenTelemetry Collector Setup (Legacy)
 
-To start a collector that prints each log message to stdout, run
-`cd tests/collector` and run
+If using the OpenTelemetry integration, you can set up collectors for trace
+data:
+
+To start a collector that prints each log message to stdout:
 
 ```bash
-docker run -p 4317:4317 -p 4318:4318 --rm -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector
+cd tests/collector
+docker run -p 4317:4317 -p 4318:4318 --rm \
+  -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml \
+  otel/opentelemetry-collector
 ```
 
-To start a Jaeger collector that starts a basic dashboard, run:
+To start a Jaeger collector with a dashboard UI:
 
 ```bash
 docker run --name jaeger \
@@ -88,3 +151,5 @@ docker run --name jaeger \
   -p 4318:4318 \
   jaegertracing/all-in-one:1.35
 ```
+
+Access the Jaeger UI at http://localhost:16686