feat: add example for telemetry facade

.env

@@ -4,10 +4,10 @@ APP_KEY=ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
 APP_DEBUG=true
 APP_URL=http://localhost
 APP_HOST=127.0.0.1
-APP_PORT=3000
+APP_PORT=8080
 
 GRPC_HOST=127.0.0.1
-GRPC_PORT=3001
+GRPC_PORT=3002
 
 GRPC_USER_HOST=127.0.0.1
 GRPC_USER_PORT=3001

app/facades/telemetry.go

@@ -0,0 +1,9 @@
+package facades
+
+import (
+	"github.com/goravel/framework/contracts/telemetry"
+)
+
+func Telemetry() telemetry.Telemetry {
+	return App().MakeTelemetry()
+}

bootstrap/app.go

@@ -12,6 +12,8 @@ import (
 	"github.com/goravel/framework/http/limit"
 	httpmiddleware "github.com/goravel/framework/http/middleware"
 	"github.com/goravel/framework/session/middleware"
+	telemetrygrpc "github.com/goravel/framework/telemetry/instrumentation/grpc"
+	telemetryhttp "github.com/goravel/framework/telemetry/instrumentation/http"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/stats"
 
@@ -50,6 +52,7 @@ func Boot() contractsfoundation.Application {
 			handler.Append(
 				httpmiddleware.Throttle("global"),
 				middleware.StartSession(),
+				telemetryhttp.Telemetry(),
 			).Recover(func(ctx http.Context, err any) {
 				facades.Log().Error(err)
 				_ = ctx.Response().String(http.StatusInternalServerError, "recover").Abort()
@@ -68,10 +71,16 @@ func Boot() contractsfoundation.Application {
 			}
 		}).
 		WithGrpcServerStatsHandlers(func() []stats.Handler {
-			return []stats.Handler{}
+			return []stats.Handler{
+				telemetrygrpc.NewServerStatsHandler(),
+			}
 		}).
 		WithGrpcClientStatsHandlers(func() map[string][]stats.Handler {
-			return map[string][]stats.Handler{}
+			return map[string][]stats.Handler{
+				"default": {
+					telemetrygrpc.NewClientStatsHandler(),
+				},
+			}
 		}).
 		WithPaths(func(paths configuration.Paths) {
 			paths.App("app")

bootstrap/providers.go

@@ -20,6 +20,7 @@ import (
 	"github.com/goravel/framework/route"
 	"github.com/goravel/framework/schedule"
 	"github.com/goravel/framework/session"
+	"github.com/goravel/framework/telemetry"
 	"github.com/goravel/framework/testing"
 	"github.com/goravel/framework/translation"
 	"github.com/goravel/framework/validation"
@@ -68,5 +69,6 @@ func Providers() []foundation.ServiceProvider {
 		&redis.ServiceProvider{},
 		&gin.ServiceProvider{},
 		&fiber.ServiceProvider{},
+		&telemetry.ServiceProvider{},
 	}
 }

config/http.go

@@ -81,6 +81,7 @@ func init() {
 				"max_idle_conns_per_host": config.Env("HTTP_CLIENT_MAX_IDLE_CONNS_PER_HOST", 2),
 				"max_conns_per_host":      config.Env("HTTP_CLIENT_MAX_CONN_PER_HOST", 0),
 				"idle_conn_timeout":       config.Env("HTTP_CLIENT_IDLE_CONN_TIMEOUT", "90s"),
+				"enable_telemetry":        true,
 			},
 		},
 	})

config/logging.go

@@ -22,7 +22,7 @@ func init() {
 		"channels": map[string]any{
 			"stack": map[string]any{
 				"driver":   "stack",
-				"channels": []string{"single", "daily"},
+				"channels": []string{"single", "daily", "otel"},
 			},
 			"single": map[string]any{
 				"driver":    "single",
@@ -39,6 +39,10 @@ func init() {
 				"print":     true,
 				"formatter": "text",
 			},
+			"otel": map[string]any{
+				"driver":          "otel",
+				"instrument_name": config.GetString("APP_NAME", "goravel/log"),
+			},
 		},
 	})
 }

config/telemetry.go

@@ -122,6 +122,56 @@ func init() {
 			},
 		},
 
+		// Instrumentation Configuration
+		//
+		// Configures the automatic instrumentation for specific components.
+		"instrumentation": map[string]any{
+			// HTTP Server Instrumentation
+			//
+			// Configures the telemetry middleware for incoming HTTP requests.
+			"http_server": map[string]any{
+				"enabled":          config.Env("OTEL_HTTP_SERVER_ENABLED", true),
+				"excluded_paths":   []string{}, // e.g., ["/health", "/metrics"]
+				"excluded_methods": []string{}, // e.g., ["OPTIONS", "HEAD"]
+			},
+
+			// HTTP Client Instrumentation
+			//
+			// Configures instrumentation for outgoing HTTP requests made through the
+			// application's HTTP client facade. This acts as a global kill switch for
+			// HTTP client telemetry across all clients.
+			//
+			// To disable telemetry for a specific client, set
+			// "http.clients.{client_name}.enable_telemetry" to false for the
+			// corresponding client configuration.
+			"http_client": map[string]any{
+				"enabled": config.Env("OTEL_HTTP_CLIENT_ENABLED", true),
+			},
+
+			// gRPC Server Instrumentation
+			//
+			// Configures the instrumentation for incoming gRPC requests to your server.
+			"grpc_server": map[string]any{
+				"enabled": config.Env("OTEL_GRPC_SERVER_ENABLED", true),
+			},
+
+			// gRPC Client Instrumentation
+			//
+			// Configures the instrumentation for outgoing gRPC calls made by your application.
+			"grpc_client": map[string]any{
+				"enabled": config.Env("OTEL_GRPC_CLIENT_ENABLED", true),
+			},
+
+			// Log Instrumentation
+			//
+			// Configures the instrumentation for the application logger.
+			// Disabling this acts as a global kill switch for sending logs to the OTel exporter,
+			// which can be useful for reducing cost/noise without changing logging config.
+			"log": map[string]any{
+				"enabled": config.Env("OTEL_LOG_ENABLED", true),
+			},
+		},
+
 		// Exporters Configuration
 		//
 		// Defines the details for connecting to external telemetry backends.
@@ -150,7 +200,11 @@ func init() {
 			"otlpmetric": map[string]any{
 				"driver":   "otlp",
 				"endpoint": config.Env("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", "http://localhost:4318"),
+
+				// Protocol: "http/protobuf", "http/json" or "grpc".
 				"protocol": config.Env("OTEL_EXPORTER_OTLP_METRICS_PROTOCOL", "http/protobuf"),
+
+				// Set to false to require TLS/SSL.
 				"insecure": config.Env("OTEL_EXPORTER_OTLP_METRICS_INSECURE", true),
 
 				// Timeout: Max time to wait for the backend to acknowledge.
@@ -167,7 +221,11 @@ func init() {
 			"otlplog": map[string]any{
 				"driver":   "otlp",
 				"endpoint": config.Env("OTEL_EXPORTER_OTLP_LOGS_ENDPOINT", "http://localhost:4318"),
+
+				// Protocol: "http/protobuf", "http/json" or "grpc".
 				"protocol": config.Env("OTEL_EXPORTER_OTLP_LOGS_PROTOCOL", "http/protobuf"),
+
+				// Set to false to require TLS/SSL.
 				"insecure": config.Env("OTEL_EXPORTER_OTLP_LOGS_INSECURE", true),
 
 				// Timeout: Max time to wait for the backend to acknowledge.
@@ -185,6 +243,22 @@ func init() {
 			// Prints telemetry data to stdout.
 			"console": map[string]any{
 				"driver": "console",
+
+				// Set to true to pretty print the output.
+				"pretty_print": false,
+			},
+
+			// Custom Exporter
+			//
+			// Use this to provide your own exporter implementation.
+			// The "via" key should contain an instance of your custom exporter.
+			"custom": map[string]any{
+				"driver": "custom",
+
+				// For traces, via should be an instance of go.opentelemetry.io/otel/sdk/trace.SpanExporter or func(context.Context) (sdktrace.SpanExporter, error)
+				// For metrics, via should be an instance of go.opentelemetry.io/otel/sdk/metric.Reader or func(context.Context) (sdkmetric.Reader, error)
+				// For log, via should be an instance of go.opentelemetry.io/otel/sdk/log.Exporter or func(context.Context) (sdklog.Exporter, error)
+				// "via": YourCustomExporterInstance,
 			},
 		},
 	})

docker-compose.yml

@@ -1,9 +1,61 @@
-version: '3'
+version: '3.8'
 
 services:
   goravel:
     build:
       context: .
     ports:
       - "3000:3000"
+    environment:
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+      - OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+      - OTEL_TRACES_EXPORTER=otlptrace
+      - OTEL_METRICS_EXPORTER=otlpmetric
+      - OTEL_LOGS_EXPORTER=otlplog
+    depends_on:
+      - otel-collector
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    restart: always
+    command: ["--config=/etc/otel-config.yaml"]
+    volumes:
+      - ./otel-config.yaml:/etc/otel-config.yaml
+    ports:
+      - "4317:4317"
+      - "4318:4318"
+
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    restart: always
+    ports:
+      - "16686:16686"
+
+  prometheus:
+    image: prom/prometheus:latest
     restart: always
+    volumes:
+      - ./prometheus.yaml:/etc/prometheus/prometheus.yml
+    command:
+      - --config.file=/etc/prometheus/prometheus.yml
+      - --web.enable-remote-write-receiver
+    ports:
+      - "9090:9090"
+
+  loki:
+    image: grafana/loki:latest
+    restart: always
+    volumes:
+      - ./loki.yaml:/etc/loki/local-config.yaml
+    command: -config.file=/etc/loki/local-config.yaml
+    ports:
+      - "3100:3100"
+
+  grafana:
+    image: grafana/grafana:latest
+    restart: always
+    ports:
+      - "3001:3000"
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin

go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/goravel/cos v1.17.0
 	github.com/goravel/example-proto v0.0.1
 	github.com/goravel/fiber v1.17.0
-	github.com/goravel/framework v1.17.0
+	github.com/goravel/framework v1.17.1-0.20260213185034-b6d4be586a85
 	github.com/goravel/gin v1.17.0
 	github.com/goravel/minio v1.17.0
 	github.com/goravel/mysql v1.17.0
@@ -83,6 +83,7 @@ require (
 	github.com/dromara/carbon/v2 v2.6.11 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.13 // indirect
 	github.com/gin-contrib/sse v1.1.0 // indirect
@@ -190,6 +191,8 @@ require (
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.64.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0 // indirect
 	go.opentelemetry.io/contrib/propagators/b3 v1.39.0 // indirect
 	go.opentelemetry.io/otel v1.39.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.15.0 // indirect

go.sum

@@ -179,6 +179,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
 github.com/fogleman/gg v1.2.1-0.20190220221249-0403632d5b90/go.mod h1:R/bRT+9gY/C5z7JzPU0zXsXHKM4/ayA+zqcVNZzPa1k=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
@@ -279,8 +281,10 @@ github.com/goravel/fiber v1.17.0 h1:XMkuz29hJzaN5mW7dK70oc6FfMDUQeYPbrLyBQoiIA8=
 github.com/goravel/fiber v1.17.0/go.mod h1:hu2eLwQ6u8ZDFsVWHeV1q0bh7g7PRQg0VZxceVr29Uc=
 github.com/goravel/file-rotatelogs/v2 v2.4.2 h1:g68AzbePXcm0V2CpUMc9j4qVzcDn7+7aoWSjZ51C0m4=
 github.com/goravel/file-rotatelogs/v2 v2.4.2/go.mod h1:23VuSW8cBS4ax5cmbV+5AaiLpq25b8UJ96IhbAkdo8I=
-github.com/goravel/framework v1.17.0 h1:a02vTMO7ETQE+fkpfndiNgSXucJKA58qB3nzm+moW6A=
-github.com/goravel/framework v1.17.0/go.mod h1:ClgXBsig8R2w+xAJT2TVxpAkazGHFtvVmNBolYT94gQ=
+github.com/goravel/framework v1.17.1-0.20260207193711-16b6ec3ccb18 h1:PVJIuuLQIKVN7n1dFxXNVdKWW+MQ87CC5wNrUFF713w=
+github.com/goravel/framework v1.17.1-0.20260207193711-16b6ec3ccb18/go.mod h1:XcENnHvnbUkm1oBbrn2vi9MAWv1jMbs2ilnEdX8i6io=
+github.com/goravel/framework v1.17.1-0.20260213185034-b6d4be586a85 h1:IwYqyg1boD+gm+SWfxlxBpEBwHIFTQjvAKqMbyz6Xlw=
+github.com/goravel/framework v1.17.1-0.20260213185034-b6d4be586a85/go.mod h1:XcENnHvnbUkm1oBbrn2vi9MAWv1jMbs2ilnEdX8i6io=
 github.com/goravel/gin v1.17.0 h1:8H66v9GaYJR9UQ7C0VOef25/r8t/BAH9ZxlvxbHprlc=
 github.com/goravel/gin v1.17.0/go.mod h1:n0W6V/H+E0mqO+Gh+UMjeBANZe//lpWJ6X7kF3kwxR8=
 github.com/goravel/minio v1.17.0 h1:WGiPP/KZl/fuDpT9THRM83wjhLCqe1oIAyNVJvVjhS4=
@@ -549,6 +553,10 @@ github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3i
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.64.0 h1:RN3ifU8y4prNWeEnQp2kRRHz8UwonAEYZl8tUzHEXAk=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.64.0/go.mod h1:habDz3tEWiFANTo6oUE99EmaFUrCNYAAg3wiVmusm70=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0 h1:ssfIgGNANqpVFCndZvcuyKbl0g+UAVcbBcqGkG28H0Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0/go.mod h1:GQ/474YrbE4Jx8gZ4q5I4hrhUzM6UPzyrqJYV2AqPoQ=
 go.opentelemetry.io/contrib/propagators/b3 v1.39.0 h1:PI7pt9pkSnimWcp5sQhUA9OzLbc3Ba4sL+VEUTNsxrk=
 go.opentelemetry.io/contrib/propagators/b3 v1.39.0/go.mod h1:5gV/EzPnfYIwjzj+6y8tbGW2PKWhcsz5e/7twptRVQY=
 go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=

loki.yaml

@@ -0,0 +1,32 @@
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+  grpc_listen_port: 9096
+
+common:
+  instance_addr: 127.0.0.1
+  path_prefix: /tmp/loki
+  storage:
+    filesystem:
+      chunks_directory: /tmp/loki/chunks
+      rules_directory: /tmp/loki/rules
+  replication_factor: 1
+  ring:
+    kvstore:
+      store: inmemory
+
+schema_config:
+  configs:
+    - from: 2020-10-24
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h
+
+limits_config:
+  allow_structured_metadata: true
+  reject_old_samples: true
+  reject_old_samples_max_age: 168h