feat: OpenTelemetry observability integration (Wave 1 / v0.7.1)

.serena/project.yml

@@ -1,9 +1,3 @@
-# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
-#  * For C, use cpp
-#  * For JavaScript, use typescript
-# Special requirements:
-#  * csharp: Requires the presence of a .sln file in the project folder.
-language: go
 
 # whether to use the project's gitignore file to ignore files
 # Added on 2025-04-07
@@ -64,5 +58,58 @@ excluded_tools: []
 # initial prompt for the project. It will always be given to the LLM upon activating the project
 # (contrary to the memories, which are loaded on demand).
 initial_prompt: ""
-
+# the name by which the project can be referenced within Serena
 project_name: "pyproc"
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default.
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+default_modes:
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+fixed_tools: []
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: utf-8
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   powershell          python              python_jedi         r                   rego
+#   ruby                ruby_solargraph     rust                scala               swift
+#   terraform           toml                typescript          typescript_vts      vue
+#   yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- go

CLAUDE.md

@@ -0,0 +1,58 @@
+# pyproc
+
+同一ホスト/同一Pod内で Go から Python を UDS 経由で低遅延 IPC するライブラリ。
+v1.0 = 機能追加ではなく「企業が採用判断できる条件の充足」（API/プロトコル固定、運用・観測・セキュリティ・互換性の明文化と自動化）。
+
+## スコープ
+
+- やること: Go→Python の UDS IPC、K8s/コンテナ配布の完成度
+- やらないこと: クロスホスト通信、任意コード実行（trusted code前提）、GPU分散
+
+## コマンド
+
+```bash
+# セットアップ
+go mod tidy && cd worker/python && uv sync --all-extras --dev && cd ../..
+
+# Go テスト（race detector 有効）
+go test -v -race ./...
+
+# Python テスト
+cd worker/python && uv run pytest -v
+
+# Go lint
+golangci-lint run ./...
+
+# Python lint + format
+cd worker/python && uv run ruff check . && uv run ruff format --check .
+
+# ベンチマーク
+make bench-quick
+```
+
+## コード規約
+
+- pip 禁止。パッケージ管理は uv のみ
+- Go エラーは `fmt.Errorf("context: %w", err)` でラップ
+- Python は全関数に型ヒント必須、Google 形式 docstring
+- Export 型/関数には doc comment 必須（Go）
+- チャネル操作は `select + context.Done()` でキャンセル可能に
+
+## SemVer方針
+
+- Public API: Go `pkg/pyproc` exported symbols, Python `expose`/`run_worker`, wire protocol, config schema
+- 0.y.z 期間: 破壊的変更は MINOR(y) を上げる
+- v1.0.0 = Public API確定、互換性テスト完備
+
+## セキュリティ
+
+docs/security.md, internal/protocol/, .claude/rules/security.md の変更時は必ずユーザーに確認を求める。
+
+## v1.0ロードマップ
+
+.ssd/ に v1.0 リリース戦略がある。openspec/ で変更提案を管理する。
+
+## 注意
+
+- 日本語で対応する
+- Go v0.4.0 と worker 0.1.0 のバージョン乖離を意識する

README.md

@@ -158,6 +158,7 @@ For detailed threat model, security architecture, and best practices, see [SECUR
 - **Minimal Overhead** - 45μs p50 latency, 200,000+ req/s with 8 workers
 - **Production Ready** - Health checks, graceful shutdown, automatic restarts
 - **Easy Deployment** - Single binary + Python scripts, no service mesh needed
+- **Full Observability** - OpenTelemetry tracing, Prometheus metrics, structured logging (v0.7.1+)
 
 ## 🚀 Quick Start (5 minutes)
 
@@ -264,6 +265,77 @@ make demo
 
 This starts a Python worker from examples/basic/worker.py and calls it from Go. The example adjusts PYTHONPATH to import the local worker/python/pyproc_worker package.
 
+## 📊 Observability (v0.7.1+)
+
+pyproc includes built-in support for distributed tracing, metrics, and structured logging.
+
+### Distributed Tracing with OpenTelemetry
+
+```go
+import (
+    "context"
+    "github.com/YuminosukeSato/pyproc/pkg/pyproc"
+    "github.com/YuminosukeSato/pyproc/pkg/pyproc/telemetry"
+)
+
+func main() {
+    // Initialize telemetry provider
+    provider, shutdown := telemetry.NewProvider(telemetry.Config{
+        ServiceName:  "my-service",
+        Enabled:      true,
+        SamplingRate: 0.01,        // 1% sampling
+        ExporterType: "stdout",    // or "otlp" for production
+    })
+    defer shutdown(context.Background())
+
+    // Create pool
+    pool, _ := pyproc.NewPool(poolOpts, logger)
+
+    // Attach tracer (opt-in)
+    pool.WithTracer(provider.Tracer("my-service"))
+
+    // All calls are now traced automatically
+    ctx := context.Background()
+    result, _ := pyproc.CallTyped[Req, Resp](ctx, pool, "predict", request)
+}
+```
+
+**Key features:**
+- ✅ Automatic span creation for all `Pool.Call()` invocations
+- ✅ W3C Trace Context propagation over Unix Domain Sockets
+- ✅ <1% overhead with 1% sampling (production target)
+- ✅ Zero overhead when disabled (no-op mode)
+- ✅ Fully backward compatible (opt-in via `WithTracer()`)
+
+### Metrics
+
+Built-in Prometheus metrics:
+
+```go
+// Expose metrics endpoint
+http.Handle("/metrics", promhttp.Handler())
+
+// Metrics automatically collected:
+// - pyproc_pool_calls_total
+// - pyproc_pool_call_duration_seconds
+// - pyproc_pool_errors_total
+// - pyproc_worker_active_connections
+```
+
+### Structured Logging
+
+```go
+import "log/slog"
+
+logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelInfo,
+}))
+
+pool, _ := pyproc.NewPool(poolOpts, logger)
+```
+
+For comprehensive observability documentation, see [docs/observability.md](docs/observability.md).
+
 ## 📚 Detailed Usage Guide
 
 ### Installation