docs: update observability documentation and tooling

- Fix docker-compose.yml: document correct env vars (MEMORY_PLUGIN_OTLP_*)
- Add SSRF override documentation (MEMORY_PLUGIN_OTLP_ALLOW_INTERNAL)
- Add --export flag to metrics.py for manual OTLP export
- Update metrics.md command help with export option
- Update CLAUDE.md observability section

Author: zircote

CLAUDE.md

@@ -253,6 +253,33 @@ def capture_service(tmp_path, monkeypatch):
 | `SECRETS_FILTER_AUDIT_ENABLED` | Enable audit logging | `true` |
 | `SECRETS_FILTER_AUDIT_DIR` | Audit log directory | `~/.local/share/memory-plugin/audit/` |
 
+### Observability Configuration (OTLP)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MEMORY_PLUGIN_OTLP_ENDPOINT` | OTLP HTTP endpoint (e.g., `http://localhost:4318`) | (none) |
+| `MEMORY_PLUGIN_OTLP_ALLOW_INTERNAL` | Allow internal/localhost endpoints (SEC-H-001 SSRF override) | `false` |
+
+To enable observability with the local Docker stack:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc for persistence
+export MEMORY_PLUGIN_OTLP_ENDPOINT=http://localhost:4318
+export MEMORY_PLUGIN_OTLP_ALLOW_INTERNAL=true
+```
+
+**Note**: The `ALLOW_INTERNAL` flag is required because the OTLP exporter has SSRF protection (SEC-H-001) that blocks localhost/private IPs by default. This is a security feature for production environments.
+
+Start the observability stack with:
+```bash
+cd docker && docker compose up -d
+```
+
+Access dashboards:
+- **Grafana**: http://localhost:3000 (admin/admin) - Memory Operations and Hook Performance dashboards
+- **Prometheus**: http://localhost:9090 - Direct metrics queries
+- **Tempo traces**: Access via Grafana → Explore → Tempo datasource (no direct web UI)
+
 ### Remote Sync (Team Collaboration)
 
 For team environments where multiple developers share memories:

commands/metrics.md

@@ -1,6 +1,6 @@
 ---
 description: Display observability metrics for the memory system
-argument-hint: "[--format=text|json|prometheus] [--filter=<pattern>]"
+argument-hint: "[--format=text|json|prometheus] [--filter=<pattern>] [--export]"
 allowed-tools: ["Bash", "Read"]
 ---
 
@@ -19,7 +19,7 @@ NAME
     metrics - Display observability metrics for the memory system
 
 SYNOPSIS
-    /memory:metrics [--format=text|json|prometheus] [--filter=<pattern>]
+    /memory:metrics [--format=text|json|prometheus] [--filter=<pattern>] [--export]
 
 DESCRIPTION
     Display collected observability metrics including counters, histograms, and gauges.
@@ -29,6 +29,7 @@ OPTIONS
     --help, -h            Show this help message
     --format=FORMAT       Output format: text (default), json, prometheus
     --filter=PATTERN      Filter metrics by name pattern (e.g., "capture", "hook")
+    --export              Export metrics/traces to OTLP endpoint (for Grafana)
 
 EXAMPLES
     /memory:metrics

docker/docker-compose.yml

@@ -8,8 +8,17 @@
 #   - Prometheus: http://localhost:9090
 #   - OTEL Collector: localhost:4317 (gRPC), localhost:4318 (HTTP)
 #
-# To send metrics from the plugin:
-#   export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# To send metrics/traces from the plugin, set these environment variables:
+#   export MEMORY_PLUGIN_OTLP_ENDPOINT=http://localhost:4318
+#   export MEMORY_PLUGIN_OTLP_ALLOW_INTERNAL=true
+#
+# The ALLOW_INTERNAL flag is required because the OTLP exporter has SSRF
+# protection that blocks localhost/private IPs by default (SEC-H-001).
+#
+# For persistent configuration, add to your shell profile (~/.bashrc, ~/.zshrc):
+#   # git-notes-memory observability
+#   export MEMORY_PLUGIN_OTLP_ENDPOINT=http://localhost:4318
+#   export MEMORY_PLUGIN_OTLP_ALLOW_INTERNAL=true
 
 services:
   # OpenTelemetry Collector - receives metrics/traces from the plugin

scripts/metrics.py

@@ -32,6 +32,11 @@ def parse_args() -> argparse.Namespace:
         default=None,
         help="Filter metrics by name pattern",
     )
+    parser.add_argument(
+        "--export",
+        action="store_true",
+        help="Export metrics to OTLP endpoint (requires MEMORY_PLUGIN_OTLP_ENDPOINT)",
+    )
     return parser.parse_args()
 
 
@@ -40,12 +45,42 @@ def main() -> int:
     args = parse_args()
     format_type = args.format
     filter_pattern = args.filter
+    do_export = args.export
 
     # Import after parsing to avoid slow imports if --help is used
     from git_notes_memory.observability.metrics import get_metrics
 
     metrics = get_metrics()
 
+    # Handle OTLP export if requested
+    if do_export:
+        from git_notes_memory.observability.exporters.otlp import (
+            export_metrics_if_configured,
+            export_traces_if_configured,
+            get_otlp_exporter,
+        )
+        from git_notes_memory.observability.tracing import get_completed_spans
+
+        exporter = get_otlp_exporter()
+        if not exporter.enabled:
+            print(
+                "OTLP export not configured. Set environment variables:\n"
+                "  export MEMORY_PLUGIN_OTLP_ENDPOINT=http://localhost:4318\n"
+                "  export MEMORY_PLUGIN_OTLP_ALLOW_INTERNAL=true",
+                file=sys.stderr,
+            )
+            return 1
+
+        # Export metrics
+        metrics_ok = export_metrics_if_configured()
+
+        # Export any pending traces
+        spans = get_completed_spans()
+        traces_ok = export_traces_if_configured(spans) if spans else True
+
+        print(f"OTLP export: metrics={'OK' if metrics_ok else 'FAILED'}, traces={'OK' if traces_ok else 'FAILED'} ({len(spans)} spans)")
+        return 0 if (metrics_ok and traces_ok) else 1
+
     if format_type == "json":
         output = metrics.export_json()
         if filter_pattern: