Skip to content

Enrich gRPC TLS handshake errors with connection context (no contrib changes)#18

Draft
zinal wants to merge 3 commits into
mainfrom
cursor/grpc-handshake-log-addresses-990a
Draft

Enrich gRPC TLS handshake errors with connection context (no contrib changes)#18
zinal wants to merge 3 commits into
mainfrom
cursor/grpc-handshake-log-addresses-990a

Conversation

@zinal

@zinal zinal commented Jun 16, 2026

Copy link
Copy Markdown
Owner

Summary

Improves :GRPC_LIBRARY ERROR diagnostics when a TLS handshake fails inside ydbd, without patching contrib/libs/grpc.

Upstream gRPC is vendored and periodically refreshed, so the implementation lives entirely in YDB-owned code.

Approach

  1. ydb/library/grpc/common/log_context.* — global gRPC log hook that:

    • always keeps internal gRPC verbosity at DEBUG so tcp tracer connect events are visible to the hook;
    • silently records recent SERVER_CONNECT / CLIENT_CONNECT events from the tcp tracer;
    • on Handshake failed ... appends connection context to the ERROR line;
    • respects configured GRPC_LIBRARY print level for all other messages.
  2. grpc_common.h — when creating a TLS client channel, registers logical grpcs://host:port target for correlation with the next outgoing TCP connect.

  3. grpc_library_helper.cpp — delegates to the new hook instead of a minimal fprintf wrapper.

Example output

:GRPC_LIBRARY ERROR: Handshake failed with fatal error SSL_ERROR_SSL: error:1408F09C:SSL routines:ssl3_get_record:http request | connection: direction=outgoing peer=ipv4:10.0.0.2:8765 target=grpcs://collector:4317
:GRPC_LIBRARY ERROR: Handshake failed with fatal error SSL_ERROR_SSL: ... | connection: direction=incoming peer=ipv4:10.0.0.5:54321

Trade-offs vs contrib patch

YDB-only (this PR) contrib patch
peer address yes (from tcp tracer) yes
local address no yes
target (logical) yes for SDK client channels yes (grpc.server_uri)
Maintenance stays in YDB tree lost on grpc vendor bump
Correlation heuristic (recent connect + thread) exact (handshake callback)

Testing

  • ./ya make --build relwithdebinfo ydb/library/grpc/common ydb/core/cms/console ydb/public/sdk/cpp/src/library/grpc/client — build succeeded.
Open in Web Open in Cursor 

cursoragent and others added 3 commits June 16, 2026 18:40
When TLS handshake fails inside ydbd, the GRPC_LIBRARY log previously
contained only the OpenSSL error without connection context. Log the
direction (incoming/outgoing), local and peer socket addresses, optional
client channel target, and the full error at the security handshaker
layer. Demote the duplicate low-level TSI message to DEBUG to avoid
two ERROR lines for the same failure.

Co-authored-by: Maksim Zinal <zinal@ydb.tech>
…rib patches

Track recent TCP connect events from gRPC tcp tracer logs inside YDB-owned
code and append peer/target details when a handshake failure is logged.
Register logical grpcs:// targets when SDK client channels are created.

Internal gRPC log verbosity is always DEBUG so connect events can be captured
even when GRPC_LIBRARY print level is ERROR; only configured severities are
written to stderr.

Co-authored-by: Maksim Zinal <zinal@ydb.tech>
@cursor cursor Bot changed the title Log peer/local addresses on gRPC SSL handshake failure Enrich gRPC TLS handshake errors with connection context (no contrib changes) Jun 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants