1)目标和边界 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 这套开源项目分两部分:1. SDK 包(packages/observability-sdk)- 提供 tracing、metrics、structured logging 三件套 - 无侵入接入 Hyperf 应用中间件 配置2. 示例平台(apps/demo-platform)- 一个最小业务 API如订单接口 - 接入 SDK 后能在 Grafana/Jaeger/Prometheus 看到完整观测数据 ---2)推荐仓库结构Monorepo hyperf-observability/ ├─ packages/ │ └─ observability-sdk/ │ ├─ composer.json │ ├─ src/ │ │ ├─ Config/ObservabilityConfig.php │ │ ├─ Context/TraceContext.php │ │ ├─ Middleware/ObservabilityMiddleware.php │ │ ├─ Logging/JsonTraceProcessor.php │ │ ├─ Metrics/RequestMetrics.php │ │ ├─ Tracing/TracerFactory.php │ │ └─ Provider/ObservabilityServiceProvider.php │ └─ tests/ ├─ apps/ │ └─ demo-platform/ │ ├─ app/Controller/OrderController.php │ ├─ config/autoload/observability.php │ ├─ config/autoload/middlewares.php │ └─ routes.php ├─ deploy/ │ ├─ docker-compose.yml │ ├─ otel-collector-config.yaml │ ├─ prometheus.yml │ └─ grafana/provisioning/... ├─ .github/workflows/ci.yml ├─ .github/workflows/release.yml ├─ LICENSE └─ README.md ---3)从0初始化命令# 1) 创建 demo 平台composercreate-project hyperf/hyperf-skeleton apps/demo-platform# 2) 创建 SDK 包目录mkdir-ppackages/observability-sdk/src packages/observability-sdk/tests# 3) SDK 依赖在 packages/observability-sdk 下composerinitcomposerrequire open-telemetry/api open-telemetry/sdk open-telemetry/exporter-otlpcomposerrequire promphp/prometheus_client_phpcomposerrequire monolog/monolog# 4) demo 平台依赖在 apps/demo-platform 下composerrequire hyperf/http-server hyperf/di hyperf/loggercomposerrequire monolog/monolog ---4)SDK 核心代码4.1配置对象 packages/observability-sdk/src/Config/ObservabilityConfig.php?php declare(strict_types1);namespace Acme\Observability\Config;final class ObservabilityConfig{publicfunction__construct(public string$serviceNamedemo-platform, public string$environmentdev, public string$otlpEndpointhttp://otel-collector:4318, public bool$enableTracingtrue, public bool$enableMetricstrue, public bool$enableLoggingtrue,){}}4.2Trace 上下文 packages/observability-sdk/src/Context/TraceContext.php?php declare(strict_types1);namespace Acme\Observability\Context;use Hyperf\Context\Context;final class TraceContext{private const KEY_TRACE_IDobs.trace_id;private const KEY_SPAN_IDobs.span_id;public staticfunctionset(string$traceId, string$spanId): void{Context::set(self::KEY_TRACE_ID,$traceId);Context::set(self::KEY_SPAN_ID,$spanId);}public staticfunctiontraceId(): ?string{returnContext::get(self::KEY_TRACE_ID);}public staticfunctionspanId(): ?string{returnContext::get(self::KEY_SPAN_ID);}public staticfunctionclear(): void{Context::set(self::KEY_TRACE_ID, null);Context::set(self::KEY_SPAN_ID, null);}}4.3Tracer 工厂 packages/observability-sdk/src/Tracing/TracerFactory.php?php declare(strict_types1);namespace Acme\Observability\Tracing;use Acme\Observability\Config\ObservabilityConfig;use OpenTelemetry\API\Trace\TracerInterface;use OpenTelemetry\SDK\Resource\ResourceInfo;use OpenTelemetry\SDK\Resource\ResourceInfoFactory;use OpenTelemetry\SDK\Trace\TracerProvider;use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;use OpenTelemetry\Contrib\Otlp\SpanExporter;use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;use OpenTelemetry\SemConv\ResourceAttributes;final class TracerFactory{public staticfunctionmake(ObservabilityConfig$cfg): TracerInterface{$transport(new OtlpHttpTransportFactory())-create($cfg-otlpEndpoint./v1/traces,application/json);$resourceResourceInfoFactory::defaultResource()-merge(ResourceInfo::create([ResourceAttributes::SERVICE_NAME$cfg-serviceName, ResourceAttributes::DEPLOYMENT_ENVIRONMENT_NAME$cfg-environment,]));$providernew TracerProvider(new BatchSpanProcessor(new SpanExporter($transport)), null,$resource);return$provider-getTracer(acme.observability);}}4.4Hyperf 中间件HTTP Span 请求时延 trace 注入 packages/observability-sdk/src/Middleware/ObservabilityMiddleware.php?php declare(strict_types1);namespace Acme\Observability\Middleware;use Acme\Observability\Context\TraceContext;use Acme\Observability\Metrics\RequestMetrics;use OpenTelemetry\API\Trace\SpanKind;use OpenTelemetry\API\Trace\TracerInterface;use Psr\Http\Message\ResponseInterface;use Psr\Http\Message\ServerRequestInterface;use Psr\Http\Server\RequestHandlerInterface;final class ObservabilityMiddleware{publicfunction__construct(privatereadonlyTracerInterface$tracer, privatereadonlyRequestMetrics$metrics,){}publicfunctionprocess(ServerRequestInterface$request, RequestHandlerInterface$handler): ResponseInterface{$path$request-getUri()-getPath();$method$request-getMethod();$startmicrotime(true);$span$this-tracer-spanBuilder($method. .$path)-setSpanKind(SpanKind::KIND_SERVER)-startSpan();$scope$span-activate();TraceContext::set($span-getContext()-getTraceId(),$span-getContext()-getSpanId());try{$response$handler-handle($request);$status$response-getStatusCode();$span-setAttribute(http.method,$method);$span-setAttribute(http.target,$path);$span-setAttribute(http.status_code,$status);$this-metrics-observeHttpRequest(method:$method, route:$path, status:(string)$status, seconds: microtime(true)-$start);return$response-withHeader(x-trace-id, TraceContext::traceId()??);}catch(\Throwable$e){$span-recordException($e);$span-setAttribute(error,true);$this-metrics-observeHttpRequest($method,$path,500, microtime(true)-$start);throw$e;}finally{$span-end();$scope-detach();TraceContext::clear();}}}4.5Metrics 采集Prometheus packages/observability-sdk/src/Metrics/RequestMetrics.php?php declare(strict_types1);namespace Acme\Observability\Metrics;use Prometheus\CollectorRegistry;use Prometheus\Storage\InMemory;final class RequestMetrics{private CollectorRegistry$registry;private\Prometheus\Histogram$httpLatency;private\Prometheus\Counter$httpTotal;publicfunction__construct(){$this-registrynew CollectorRegistry(new InMemory());$this-httpLatency$this-registry-getOrRegisterHistogram(app,http_request_duration_seconds,HTTP request latency,[method,route,status],[0.01,0.05,0.1,0.3,1,3,10]);$this-httpTotal$this-registry-getOrRegisterCounter(app,http_requests_total,HTTP requests count,[method,route,status]);}publicfunctionobserveHttpRequest(string$method, string$route, string$status, float$seconds): void{$labels[$method,$route,$status];$this-httpLatency-observe($seconds,$labels);$this-httpTotal-inc($labels);}publicfunctionrenderPrometheus(): string{$renderernew\Prometheus\RenderTextFormat();return$renderer-render($this-registry-getMetricFamilySamples());}}4.6日志处理器自动注入 trace_id/span_id packages/observability-sdk/src/Logging/JsonTraceProcessor.php?php declare(strict_types1);namespace Acme\Observability\Logging;use Acme\Observability\Context\TraceContext;final class JsonTraceProcessor{publicfunction__invoke(array$record): array{$record[extra][trace_id]TraceContext::traceId();$record[extra][span_id]TraceContext::spanId();return$record;}}---5)在 demo-platform 接入 SDK5.1配置文件 apps/demo-platform/config/autoload/observability.php?phpreturn[service_nameenv(OBS_SERVICE_NAME,demo-platform),environmentenv(APP_ENV,dev),otlp_endpointenv(OBS_OTLP_ENDPOINT,http://otel-collector:4318),];5.2中间件注册 apps/demo-platform/config/autoload/middlewares.php?phpreturn[http[Acme\Observability\Middleware\ObservabilityMiddleware::class,],];5.3示例业务接口 apps/demo-platform/app/Controller/OrderController.php?php declare(strict_types1);namespace App\Controller;use Hyperf\HttpServer\Contract\ResponseInterface;use Psr\Log\LoggerInterface;final class OrderController{publicfunction__construct(privatereadonlyLoggerInterface$logger){}publicfunctionshow(ResponseInterface$response, int$id){$this-logger-info(query order,[order_id$id]);return$response-json([id$id,statuspaid,amount1999]);}}5.4暴露 /metrics // routes.php use Hyperf\HttpServer\Router\Router;use Acme\Observability\Metrics\RequestMetrics;use Psr\Container\ContainerInterface;Router::get(/orders/{id:\d},[App\Controller\OrderController::class,show]);Router::get(/metrics,function(ContainerInterface$container){/** var RequestMetrics$metrics*/$metrics$container-get(RequestMetrics::class);return$metrics-renderPrometheus();});---6)可观测基础设施本地一键跑 deploy/docker-compose.yml最小组合 version:3.8services: otel-collector: image: otel/opentelemetry-collector-contrib:0.100.0 command:[--config/etc/otelcol/config.yaml]volumes: - ./otel-collector-config.yaml:/etc/otelcol/config.yaml ports: -4318:4318-8889:8889jaeger: image: jaegertracing/all-in-one:1.57 ports: -16686:16686prometheus: image: prom/prometheus:v2.52.0 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml ports: -9090:9090grafana: image: grafana/grafana:11.0.0 ports: -3000:3000deploy/otel-collector-config.yaml核心 receivers: otlp: protocols: http: exporters: jaeger: endpoint: jaeger:14250 tls: insecure:trueprometheus: endpoint:0.0.0.0:8889 service: pipelines: traces: receivers:[otlp]exporters:[jaeger]---7)开源发布流程完整1. License: MIT 或 Apache-2.02. README 必须含: -5分钟快速开始 - 架构图 - 指标清单QPS、P95、错误率 - 常见问题trace 丢失、标签爆炸3. SECURITY.md: 漏洞提交邮箱和响应 SLA4. Packagist 发布 SDK: - packages/observability-sdk 独立 composer.json - 打 tag: v0.1.05. 示例平台独立运行: -dockercompose up-d- php bin/hyperf.php start ---8)CI/CD最少要有 .github/workflows/ci.yml 建议包含: - PHPStan - PHPUnit - Infection可选做变异测试 -composervalidate - SDK 与 demo 的集成测试发请求后校验 /metrics 有数据 ---9)版本策略持续维护 - v0.x: 快速迭代 API不承诺稳定 - v1.0: 冻结公共接口 - 每次发布输出: - Breaking changes - 新增指标 - 性能变化例如中间件耗时 0.2ms ---10)你最容易踩的6个坑1. 把 route 直接用原始 URL会导致高基数Prometheus 爆炸2. 日志没带 trace_id排障断链3. 异步任务没传递上下文trace 断裂4. /metrics 混入业务鉴权中间件被拦截5. 观测 SDK 抛异常影响主流程SDK 必须“失败隔离”6. 指标标签过多method/route/status 以外谨慎加 --- 这套骨架可以直接作为开源项目第一版: 先把 Middleware Metrics Log Processor Docker 观测栈 CI 发出来社区就能跑通端到端链路再逐步补齐 SQL span、队列 span、告警规则和 Grafana dashboard 模板。