feat: [#726] Add gRPC telemetry instrumentation [4] by krishankumar01 · Pull Request #1305 · goravel/framework

krishankumar01 · 2025-12-17T11:53:12Z

📑 Description

This PR introduces stats.Handler support to enable metrics emission and trace propagation for both gRPC servers and clients. Specifically, it exposes new NewServerStatsHandler and NewClientStatsHandler utilities via the github.com/framework/telemetry/instrumentation/grpc package.

Registration

You can register these stats handlers using the new ClientStatsHandlerGroups and ServerStatsHandlers methods on the gRPC facade, typically within your custom Service Providers.

Note

These handlers usually depend on the Telemetry facade. If the Telemetry service is not available or registered, the system will log a warning to prevent issues with nil service providers.

Example: Registering in a Service Provider

func (s *GrpcServiceProvider) Boot() {
    // Register a client handler for a specific group (e.g., "user")
    facades.Grpc().ClientStatsHandlerGroups(map[string][]stats.Handler{
        "user": { 
            telemetrygrpc.NewClientStatsHandler(),
        },
    })

    // Register a global server handler
    facades.Grpc().ServerStatsHandlers([]stats.Handler{
        telemetrygrpc.NewServerStatsHandler(),
    })
}

Warning

Important Configuration Note
When registering client handlers, the key you use (e.g., "user") acts as a "group name." For the handler to actually take effect, this same group name must be listed in your config/grpc.go file under the client's stats_handlers array. The framework automatically loads the Stats Handlers assigned to that group key.

Example: config/grpc.go

// In your configuration, you link the "user" group to this client
"clients": map[string]any{
    "user_service": map[string]any{
       "host":         config.Env("GRPC_USER_HOST", "localhost"),
       "port":         config.Env("GRPC_USER_PORT", "50051"),
       "stats_handlers": []string{"user"}, // <--- This key ("user") links to the registration above
    },
},

Bootstrap Configuration

For applications using the new slim skeleton, you can also configure these handlers directly in bootstrap/app.go using the fluent WithGrpcClientStatsHandlers and WithGrpcServerStatsHandlers methods.

Options

The instrumentation/grpc package exposes several options to further customize the handlers, such as WithFilter (to skip instrumentation based on specific criteria), WithSpanAttributes, and WithMetricAttributes.

Example: Using Filters and Attributes

telemetrygrpc.NewClientStatsHandler(
    // Option: Skip tracing for health check endpoints
    telemetrygrpc.WithFilter(func(info *stats.RPCTagInfo) bool {
        return info.FullMethodName != "/grpc.health.v1.Health/Check"
    }),
    
    // Option: Add custom attributes to metrics (these are extra other than resources defined in config/telemetry.go)
    telemetrygrpc.WithMetricAttributes(telemetry.String("client", "user")),
)

Configuration

General tracing and metrics settings (exporters, sampling, etc.) can continue to be customized in config/telemetry.go.

Screenshots

✅ Checks

Added test cases for my code

codecov · 2025-12-17T11:56:24Z

Codecov Report

❌ Patch coverage is 94.78261% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.41%. Comparing base (eec12ad) to head (82a9a58).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
grpc/application.go	93.65%	2 Missing and 2 partials ⚠️
foundation/application_builder.go	90.47%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1305      +/-   ##
==========================================
+ Coverage   69.20%   69.41%   +0.20%     
==========================================
  Files         280      282       +2     
  Lines       16517    16630     +113     
==========================================
+ Hits        11431    11543     +112     
+ Misses       4599     4596       -3     
- Partials      487      491       +4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR adds automatic HTTP instrumentation for OpenTelemetry tracing and metrics to the Goravel framework. It introduces a configurable middleware that creates spans, records metrics (request duration, body sizes), and propagates trace context for incoming HTTP requests.

Adds a new HTTP telemetry middleware with configurable span naming, path/method exclusion, and custom filters
Introduces global telemetry and config facades in the service provider for convenient access
Provides configuration options for enabling/disabling instrumentation and customizing behavior

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
telemetry/service_provider.go	Adds global facades for Config and Telemetry, and updates Boot method to initialize them
telemetry/instrumentation/http/middleware.go	Implements HTTP server instrumentation middleware with tracing and metrics collection
telemetry/instrumentation/http/config.go	Defines configuration structure and options for HTTP instrumentation
telemetry/alias.go	Adds KeyValue type alias for OpenTelemetry attributes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

telemetry/instrumentation/http/middleware.go

telemetry/instrumentation/http/config.go

github-actions

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.50.

Benchmark suite	Current: `3c4d11a`	Previous: `91bf06d`	Ratio
`Benchmark_Fatal`	`5e-7` ns/op 0 B/op 0 allocs/op	`2e-7` ns/op 0 B/op 0 allocs/op	`2.50`
`Benchmark_Fatal - ns/op`	`5e-7` ns/op	`2e-7` ns/op	`2.50`

This comment was automatically generated by workflow using github-action-benchmark.

Copilot

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

grpc/application.go

telemetry/instrumentation/log/mapper.go

telemetry/instrumentation/grpc/option.go

hwbrzzl

Great PR, LGTM 👍 Could you fill the PR description and add some screenshots for the testing and show how to use the handler?

grpc/application_test.go

telemetry/instrumentation/grpc/handler_test.go

Copilot

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

telemetry/instrumentation/grpc/handler.go

grpc/application.go

Copilot

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

telemetry/instrumentation/grpc/handler_test.go

telemetry/instrumentation/grpc/handler.go

grpc/application.go

Copilot

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

grpc/application.go

Copilot · 2025-12-22T21:07:43Z

grpc/application.go

+	for _, h := range app.serverStatsHandlers {
+		if h == nil {
+			continue
+		}
+		opts = append(opts, grpc.StatsHandler(h))
+	}


gRPC only supports registering one stats handler per server. When multiple grpc.StatsHandler() calls are made, only the last one takes effect (they overwrite each other). This loop will result in only the last non-nil handler being registered, making all previous handlers ineffective.

If multiple handlers are needed, consider creating a composite stats handler that internally delegates to multiple handlers, or document that only one handler should be registered.

@copilot No, this behavior has already changed. gRPC now supports multiple StatsHandlers, and all of them are used.

krishankumar01 · 2025-12-22T21:42:06Z

Great PR, LGTM 👍 Could you fill the PR description and add some screenshots for the testing and show how to use the handler?

I have added the steps to enable auto telemetry for the gRPC server and client, along with screenshots I used to test the feature locally. I have also optimized the gRPC facade to support the new requirements and provided clearer warnings on how to use it.

hwbrzzl

func (s *GrpcServiceProvider) Boot() {
    // Register a client handler for a specific group (e.g., "user")
    facades.Grpc().ClientStatsHandlerGroups(map[string][]stats.Handler{
        "user": { 
            telemetrygrpc.NewClientStatsHandler(),
        },
    })

    // Register a global server handler
    facades.Grpc().ServerStatsHandlers([]stats.Handler{
        telemetrygrpc.NewServerStatsHandler(),
    })
}

We can use the With* functions instead of the above, correct?

"interceptors": []string{"user"} is for interceptor, should a new configuration for StatsHandler be added in the config file?

krishankumar01 · 2025-12-23T06:16:36Z

We can use the With* functions instead of the above, correct?

Yes, you can use With* methods inside bootstrap/app.go.

"interceptors": []string{"user"} is for interceptor, should a new configuration for StatsHandler be added in the config file?

I thought it would be more convenient for users to use the same key for both and register it in one place. Since interceptors and stats handlers are different, I added a new stats_handlers key to the client config.

hwbrzzl

LGTM 👍

krishankumar01 added 3 commits December 13, 2025 19:52

add telemetry middleware for http server auto instrumentation

e645c4b

add telemetry middleware for http server auto instrumentation

55be4b8

rename config to server config

d8f963c

krishankumar01 requested a review from a team as a code owner December 17, 2025 11:53

Copilot AI review requested due to automatic review settings December 17, 2025 11:53

Copilot started reviewing on behalf of krishankumar01 December 17, 2025 11:53 View session

Merge branch 'master' into kkumar-gcc/#726-auto-instrumentation

57e00ed

Copilot AI reviewed Dec 17, 2025

View reviewed changes

krishankumar01 marked this pull request as draft December 17, 2025 16:44

krishankumar01 added 2 commits December 19, 2025 00:43

add tracerProvider and meterProvider in telemetry facade

703ef96

add grpc auto instrumentation stats handler

caec3b0

krishankumar01 changed the title ~~Kkumar gcc/#726 auto instrumentation~~ feat: [#726] Add HTTP and gRPC telemetry instrumentation [4] Dec 18, 2025

use otelog.ValueFromAttribute

621acba

krishankumar01 marked this pull request as ready for review December 21, 2025 06:57

krishankumar01 marked this pull request as draft December 21, 2025 06:57

krishankumar01 added 2 commits December 21, 2025 12:36

Merge branch 'master' into kkumar-gcc/#726-auto-instrumentation

c2c73a7

optimise package import order

4d8e1eb

github-actions bot reviewed Dec 21, 2025

View reviewed changes

krishankumar01 added 7 commits December 21, 2025 22:51

add skeleton http transport

5f14351

add stats handler groups in grpc

08c6bec

update application test cases

937da6f

update grpc mocks

2f3a4f7

add test cases for grpc stats handler

b39ddad

optimise application.go

861ac84

remove http instrumentation

2e0070f

krishankumar01 changed the title ~~feat: [#726] Add HTTP and gRPC telemetry instrumentation [4]~~ feat: [#726] Add gRPC telemetry instrumentation [4] Dec 22, 2025

krishankumar01 marked this pull request as ready for review December 22, 2025 07:21

krishankumar01 requested a review from Copilot December 22, 2025 07:21

Copilot started reviewing on behalf of krishankumar01 December 22, 2025 07:22 View session

Copilot AI reviewed Dec 22, 2025

View reviewed changes

minor fix

acf313d

hwbrzzl reviewed Dec 22, 2025

View reviewed changes

grpc/application_test.go Outdated Show resolved Hide resolved

telemetry/instrumentation/grpc/handler_test.go Outdated Show resolved Hide resolved

krishankumar01 added 2 commits December 22, 2025 17:58

use once in test cases

6230dbe

add new methods in application builder to configure application builder

dc7aa10

krishankumar01 requested a review from Copilot December 22, 2025 19:48

Copilot started reviewing on behalf of krishankumar01 December 22, 2025 19:48 View session

krishankumar01 added 2 commits December 23, 2025 01:21

rename gRPC stats handlers

a178814

add test cases for new method TracerProvider and MeterProvider

3c4d11a

Copilot AI reviewed Dec 22, 2025

View reviewed changes

telemetry/instrumentation/grpc/handler.go Show resolved Hide resolved

grpc/application.go Show resolved Hide resolved

grpc/application.go Show resolved Hide resolved

krishankumar01 added 2 commits December 23, 2025 01:28

remove unnecessary nil check

5981e3a

optimize gRPC server instance creation

5b66ef4

krishankumar01 requested a review from Copilot December 22, 2025 20:43

Copilot started reviewing on behalf of krishankumar01 December 22, 2025 20:43 View session

Copilot AI reviewed Dec 22, 2025

View reviewed changes

krishankumar01 added 2 commits December 23, 2025 02:19

make error message to warning

89b4c05

make error message to warning

179b5a6

krishankumar01 requested a review from Copilot December 22, 2025 21:03

Copilot started reviewing on behalf of krishankumar01 December 22, 2025 21:03 View session

Copilot AI reviewed Dec 22, 2025

View reviewed changes

Copilot AI mentioned this pull request Dec 22, 2025

Address feedback on gRPC multiple StatsHandler support #1311

Closed

goravel deleted a comment from Copilot AI Dec 22, 2025

krishankumar01 added the 🚀 Review Ready label Dec 22, 2025

hwbrzzl reviewed Dec 23, 2025

View reviewed changes

add stats_handlers key

82a9a58

hwbrzzl approved these changes Dec 23, 2025

View reviewed changes

krishankumar01 merged commit 07de65f into master Dec 23, 2025
14 checks passed

krishankumar01 deleted the kkumar-gcc/#726-auto-instrumentation branch December 23, 2025 07:24

Conversation

krishankumar01 commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📑 Description

Registration

Bootstrap Configuration

Options

Configuration

Screenshots

✅ Checks

Uh oh!

codecov bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

⚠️ Performance Alert ⚠️

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hwbrzzl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

krishankumar01 Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

krishankumar01 commented Dec 22, 2025

Uh oh!

hwbrzzl left a comment

Choose a reason for hiding this comment

Uh oh!

krishankumar01 commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hwbrzzl left a comment

krishankumar01 commented Dec 17, 2025 •

edited

Loading

codecov bot commented Dec 17, 2025 •

edited

Loading

github-actions bot left a comment •

edited

Loading

krishankumar01 commented Dec 23, 2025 •

edited

Loading