A118: TLS Telemetry by gtcooke94 · Pull Request #550 · grpc/proposal

gtcooke94 · 2026-05-18T15:40:55Z

The gRFC to support authentication telemetry in the TLS stack for handshake and TLS offload operation monitoring.

ejona86

This looks good. I'll delay giving my Approval until others have, and then I'll Approve+merge when it seems there's concensus.

ejona86 · 2026-05-27T17:44:07Z

+from the labels.
+
+* `grpc.client.tls.handshakes`
+


Missing the instrument type (counter), the unit ({handshake}), and a description. The description should say it is experimental.

The histograms have the instrument type, but are still missing the unit (s) and description.

It is still missing a description.

markdroth

This looks good overall! My comments are all relatively minor.

Please let me know if you have any questions.

dfawley

Did we want to find someone from otel to review the propsed metrics before we implement this? I don't think any of us are experts in this area.

dfawley · 2026-06-03T15:12:09Z

+			duration := time.Since(startTime).Seconds()
+     <increment metric>


Which metric is this, specifically? The ones defined above all seem to be finer-grained than this. And grpc.client.tls.handshakes is just a counter, so doesn't need a duration?

My bad, this was from when we still had the handshake at a latency metric. Updated the code snippet.

OK thanks. One other nit here is that you're mixing tabs and spaces on the different lines, so the alignment is off for me.

dfawley · 2026-06-03T15:15:49Z

+
+| Label Name | Required/Optional | Description |
+| :--- | :--- | :--- |
+| `grpc.status` | Required | Result of the certificate selection offloading, in the format of a gRPC status code (as defined in [A66]). |


Copy/paste-o from above. "Result of the private key signing...."

dfawley · 2026-06-03T15:16:54Z

+understanding authentication behavior. An enum describing the type of resumption
+used (or none) will be created - it can be extended in the future to make


This says "or none" but there is no corresponding NONE enum value below?

FULL_HANDSHAKE means no resumption was done - should we rename to NO_RESUMPTION?

I don't feel too strongly about the names, but it might want a comment. But what exactly does "RESUMED_HANDSHAKE" actually mean, relative to the other future things you suggested could be added in the future like "ticket-based resumption vs. session-based resumption"? Is "RESUMED_HANDSHAKE" actually "SESSION_RESUMPTION"?

RESUMED_HANDSHAKE means that it was resumed, with no specificity on session or ticket

dfawley · 2026-06-03T15:17:11Z

+single place: `internal/transport/http2_client.go` inside `NewHTTP2Client` via
+`transportCreds.ClientHandshake`. Server handshakes are also performed in a
+single place: `internal/transport/http2_server.go` inside `NewServerTransport`
+via `config.Credentials.ServerHandshake`. We can incremement the metrics here


Whoops, missed this in the review, fixed

dfawley · 2026-06-03T15:17:53Z

+| Label Name | Required/Optional | Description |
+| :--- | :--- | :--- |
+| `grpc.tls.handshake.result` | Required | The `TlsTelemetryHandshakeResult` enum string indicating success or the reason for handshake failure. |
+| `grpc.tls.handshake.resumed` | Optional | The `TlsResumptionType`  enum string  indicating if and how the handshake was resumed. |


dfawley · 2026-06-03T15:23:25Z

+The following metrics are count metrics, with the primary information coming
+from the labels.
+
+* `grpc.client.tls.handshakes` (unit: handshakes type: counter. This is experimental.)


The unit here should be "{handshake}" (the braces and everything are important for otel). And "int64 counter".

dfawley · 2026-06-03T15:23:42Z

+| `grpc.lb.locality` | Optional | The locality to which the traffic is being sent (as defined in [A78], [A94]). |
+| `grpc.lb.backend_service` | Optional | The backend service to which the traffic is being sent (as defined in [A89], [A94]). |
+
+* `grpc.server.tls.handshakes` (unit: handshakes type: counter. This is experimental.)


dfawley · 2026-06-03T15:24:11Z

+
+The following metrics are non-per-call bucketed latency metrics that report the duration of offloaded cryptographic operations.
+
+* `grpc.server.tls.offload_certificate_selection_duration` (unit: float64 seconds, type: histogram - latency buckets defined in [A66]. This is experimental.)


"float64" isn't a unit. I think you want "unit: s" and "type: float64 histogram".

dfawley · 2026-06-03T18:00:22Z

+ 	if transportCreds != nil {
+		isTLS := transportCreds.Info().SecurityProtocol == "tls"
+ 		conn, authInfo, err = transportCreds.ClientHandshake(connectCtx, addr.ServerName, conn)
+		if isTLS {


Other thought: do we want to read the authInfo returned by the handshake to determine whether TLS was involved (I guess cast it to TLSInfo?) or trust the creds string directly? I don't know that it matters at all, but it's something to ponder, perhaps.

FYI: Both the tls creds and xds creds today set this field to "tls". Similarly, both of them set AuthInfo to TLSInfo. Maybe the idea was always to include xds creds as well, in which case we are good.

Either way - I don't see a reason using XDS creds should preclude folks from monitoring - if it's doing TLS and we have TLS monitoring, the user can get monitoring?

As for how we want to see if it's TLS - can we discuss on the implementation PR since it's more of an impl detail? This is meant more as a demonstrative snippet, not a code source of truth.

ejona86 · 2026-06-05T17:45:06Z

@mbissa, can you look at this from the metrics definition perspective (did we define everything we needed to define)?

markdroth

This looks good, modulo updating the C++ implementation details.

markdroth · 2026-06-09T21:12:30Z

@@ -185,7 +185,7 @@ In the few use-cases where TSI is not called via gRPC, we will ensure that
 metric incrementation is not performed.

 // TODO: Update this comment to be more accurate based on the impl PR


Please remove this line.

gtcooke94 added 7 commits May 18, 2026 15:40

initial commit

1454e78

Add content to template.

c134e60

change filename

da198cb

rename to result

26aab2a

update more

df34d09

added extra labels

7290804

add TOODs for new labels

02216f5

gtcooke94 changed the title ~~[A118] Authentication Telemetry~~ [A118] TLS Telemetry May 20, 2026

gtcooke94 requested review from dfawley, easwars, ejona86, markdroth and matthewstevenson88 May 20, 2026 14:40

matthewstevenson88 reviewed May 20, 2026

View reviewed changes

gtcooke94 added 2 commits May 20, 2026 16:58

rename to TlsTelemetryHandshakeResult

beb8f75

address PR comments

3cc7cbd

gtcooke94 requested a review from matthewstevenson88 May 21, 2026 16:18

gtcooke94 added 2 commits May 21, 2026 16:19

update header for handshake result enum

b40d876

updates

10157d0

matthewstevenson88 reviewed May 22, 2026

View reviewed changes

swap order

b02596a

gtcooke94 changed the title ~~[A118] TLS Telemetry~~ A118: TLS Telemetry May 22, 2026

a few links

461f846

matthewstevenson88 approved these changes May 22, 2026

View reviewed changes

ejona86 reviewed May 27, 2026

View reviewed changes

add types and experimental

ccbf983

markdroth reviewed Jun 3, 2026

View reviewed changes

Comment thread A118-tls-telemetry.md Outdated

Comment thread A118-tls-telemetry.md Outdated

Comment thread A118-tls-telemetry.md

Comment thread A118-tls-telemetry.md Outdated

Comment thread A118-tls-telemetry.md Outdated

Comment thread A118-tls-telemetry.md Outdated

address roth@ PR comments

055fabc

dfawley reviewed Jun 3, 2026

View reviewed changes

address doug comments

844ab68

typo

015f214

dfawley reviewed Jun 3, 2026

View reviewed changes

dfawley approved these changes Jun 5, 2026

View reviewed changes

dfawley requested a review from mbissa June 5, 2026 17:44

ejona86 requested a review from mbissa June 5, 2026 17:44

easwars reviewed Jun 5, 2026

View reviewed changes

Comment thread A118-tls-telemetry.md

Comment thread A118-tls-telemetry.md

markdroth approved these changes Jun 9, 2026

View reviewed changes

Comment thread A118-tls-telemetry.md Outdated

impl detail on CollectionScope

70e4eaf

markdroth reviewed Jun 9, 2026

View reviewed changes

easwars approved these changes Jun 9, 2026

View reviewed changes

		+ duration := time.Since(startTime).Seconds()
		+ <increment metric>

		understanding authentication behavior. An enum describing the type of resumption
		used (or none) will be created - it can be extended in the future to make

	\| `grpc.tls.handshake.resumed` \| Optional \| The `TlsResumptionType` enum string indicating if and how the handshake was resumed. \|
	\| `grpc.tls.handshake.resumed` \| Optional \| The `TlsResumptionType` enum string indicating if and how the handshake was resumed. \|


		The following metrics are non-per-call bucketed latency metrics that report the duration of offloaded cryptographic operations.

		* `grpc.server.tls.offload_certificate_selection_duration` (unit: float64 seconds, type: histogram - latency buckets defined in [A66]. This is experimental.)

		@@ -185,7 +185,7 @@ In the few use-cases where TSI is not called via gRPC, we will ensure that
		metric incrementation is not performed.

		// TODO: Update this comment to be more accurate based on the impl PR

Conversation

gtcooke94 commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ejona86 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markdroth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dfawley left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gtcooke94 commented May 18, 2026 •

edited

Loading