|
| 1 | +// The MIT License |
| 2 | +// |
| 3 | +// Copyright (c) 2025 Temporal Technologies Inc. All rights reserved. |
| 4 | +// |
| 5 | +// Permission is hereby granted, free of charge, to any person obtaining a copy |
| 6 | +// of this software and associated documentation files (the "Software"), to deal |
| 7 | +// in the Software without restriction, including without limitation the rights |
| 8 | +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 9 | +// copies of the Software, and to permit persons to whom the Software is |
| 10 | +// furnished to do so, subject to the following conditions: |
| 11 | +// |
| 12 | +// The above copyright notice and this permission notice shall be included in |
| 13 | +// all copies or substantial portions of the Software. |
| 14 | +// |
| 15 | +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 16 | +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 17 | +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 18 | +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 19 | +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 20 | +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
| 21 | +// THE SOFTWARE. |
| 22 | + |
| 23 | +package nexus |
| 24 | + |
| 25 | +import ( |
| 26 | + "crypto/tls" |
| 27 | + "net/http/httptrace" |
| 28 | + "time" |
| 29 | + |
| 30 | + "go.temporal.io/server/common/dynamicconfig" |
| 31 | + "go.temporal.io/server/common/log" |
| 32 | + "go.temporal.io/server/common/log/tag" |
| 33 | +) |
| 34 | + |
| 35 | +type HTTPClientTraceProvider interface { |
| 36 | + // NewTrace returns a *httptrace.ClientTrace which provides hooks to invoke at each point in the HTTP request |
| 37 | + // lifecycle. This trace must be added to the HTTP request context using httptrace.WithClientTrace for the hooks to |
| 38 | + // be invoked. The provided logger should already be tagged with relevant request information |
| 39 | + // e.g. using log.With(logger, tag.RequestID(id), tag.Operation(op), ...). |
| 40 | + NewTrace(attempt int32, logger log.Logger) *httptrace.ClientTrace |
| 41 | +} |
| 42 | + |
| 43 | +// HTTPTraceConfig is the dynamic config for controlling Nexus HTTP request tracing behavior. |
| 44 | +// The default is nil and the conversion function does not do any actual conversion because this should be wrapped by |
| 45 | +// a dynamicconfig.NewGlobalCachedTypedValue with the actual conversion function so that it is cached. |
| 46 | +var HTTPTraceConfig = dynamicconfig.NewGlobalTypedSettingWithConverter( |
| 47 | + "system.nexusHTTPTraceConfig", |
| 48 | + func(a any) (any, error) { return a, nil }, |
| 49 | + nil, |
| 50 | + `Configuration options for controlling additional tracing for Nexus HTTP requests. Fields: Enabled, MinAttempt, MaxAttempt, Hooks. See HTTPClientTraceConfig comments for more detail.`, |
| 51 | +) |
| 52 | + |
| 53 | +type HTTPClientTraceConfig struct { |
| 54 | + // Enabled controls whether any additional tracing will be invoked. Default false. |
| 55 | + Enabled bool |
| 56 | + // MinAttempt is the first operation attempt to include additional tracing. Default 2. Setting to 0 or 1 will add tracing to all requests and may be expensive. |
| 57 | + MinAttempt int32 |
| 58 | + // MaxAttempt is the maximum operation attempt to include additional tracing. Default 2. Setting to 0 means no maximum. |
| 59 | + MaxAttempt int32 |
| 60 | + // Hooks is the list of method names to invoke with extra tracing. See httptrace.ClientTrace for more detail. |
| 61 | + // Defaults to all implemented hooks: GetConn, GotConn, ConnectStart, ConnectDone, DNSStart, DNSDone, TLSHandshakeStart, TLSHandshakeDone, WroteRequest, GotFirstResponseByte. |
| 62 | + Hooks []string |
| 63 | +} |
| 64 | + |
| 65 | +var defaultHTTPClientTraceConfig = HTTPClientTraceConfig{ |
| 66 | + Enabled: false, |
| 67 | + MinAttempt: 2, |
| 68 | + MaxAttempt: 2, |
| 69 | + // Set to nil here because of dynamic config conversion limitations. |
| 70 | + Hooks: []string(nil), |
| 71 | +} |
| 72 | + |
| 73 | +var defaultHTTPClientTraceHooks = []string{"GetConn", "GotConn", "ConnectStart", "ConnectDone", "DNSStart", "DNSDone", "TLSHandshakeStart", "TLSHandshakeDone", "WroteRequest", "GotFirstResponseByte"} |
| 74 | + |
| 75 | +func convertHTTPClientTraceConfig(in any) (HTTPClientTraceConfig, error) { |
| 76 | + cfg, err := dynamicconfig.ConvertStructure(defaultHTTPClientTraceConfig)(in) |
| 77 | + if err != nil { |
| 78 | + cfg = defaultHTTPClientTraceConfig |
| 79 | + } |
| 80 | + if len(cfg.Hooks) == 0 { |
| 81 | + cfg.Hooks = defaultHTTPClientTraceHooks |
| 82 | + } |
| 83 | + return cfg, nil |
| 84 | +} |
| 85 | + |
| 86 | +type LoggedHTTPClientTraceProvider struct { |
| 87 | + Config *dynamicconfig.GlobalCachedTypedValue[HTTPClientTraceConfig] |
| 88 | +} |
| 89 | + |
| 90 | +func NewLoggedHTTPClientTraceProvider(dc *dynamicconfig.Collection) HTTPClientTraceProvider { |
| 91 | + return &LoggedHTTPClientTraceProvider{ |
| 92 | + Config: dynamicconfig.NewGlobalCachedTypedValue(dc, HTTPTraceConfig, convertHTTPClientTraceConfig), |
| 93 | + } |
| 94 | +} |
| 95 | + |
| 96 | +//nolint:revive // cognitive complexity (> 25 max) but is just adding a logging function for each method in the list. |
| 97 | +func (p *LoggedHTTPClientTraceProvider) NewTrace(attempt int32, logger log.Logger) *httptrace.ClientTrace { |
| 98 | + config := p.Config.Get() |
| 99 | + if !config.Enabled { |
| 100 | + return nil |
| 101 | + } |
| 102 | + if attempt < config.MinAttempt { |
| 103 | + return nil |
| 104 | + } |
| 105 | + if config.MaxAttempt > 0 && attempt > config.MaxAttempt { |
| 106 | + return nil |
| 107 | + } |
| 108 | + |
| 109 | + clientTrace := &httptrace.ClientTrace{} |
| 110 | + for _, h := range config.Hooks { |
| 111 | + switch h { |
| 112 | + case "GetConn": |
| 113 | + clientTrace.GetConn = func(hostPort string) { |
| 114 | + logger.Info("attempting to get HTTP connection for Nexus request", |
| 115 | + tag.Timestamp(time.Now().UTC()), |
| 116 | + tag.Address(hostPort)) |
| 117 | + } |
| 118 | + case "GotConn": |
| 119 | + clientTrace.GotConn = func(info httptrace.GotConnInfo) { |
| 120 | + logger.Info("got HTTP connection for Nexus request", |
| 121 | + tag.Timestamp(time.Now().UTC()), |
| 122 | + tag.NewBoolTag("reused", info.Reused), |
| 123 | + tag.NewBoolTag("was-idle", info.WasIdle), |
| 124 | + tag.NewDurationTag("idle-time", info.IdleTime)) |
| 125 | + } |
| 126 | + case "ConnectStart": |
| 127 | + clientTrace.ConnectStart = func(network, addr string) { |
| 128 | + logger.Info("starting dial for new connection for Nexus request", |
| 129 | + tag.Timestamp(time.Now().UTC()), |
| 130 | + tag.Address(addr), |
| 131 | + tag.NewStringTag("network", network)) |
| 132 | + } |
| 133 | + case "ConnectDone": |
| 134 | + clientTrace.ConnectDone = func(network, addr string, err error) { |
| 135 | + logger.Info("finished dial for new connection for Nexus request", |
| 136 | + tag.Timestamp(time.Now().UTC()), |
| 137 | + tag.Address(addr), |
| 138 | + tag.NewStringTag("network", network), |
| 139 | + tag.Error(err)) |
| 140 | + } |
| 141 | + case "DNSStart": |
| 142 | + clientTrace.DNSStart = func(info httptrace.DNSStartInfo) { |
| 143 | + logger.Info("starting DNS lookup for Nexus request", |
| 144 | + tag.Timestamp(time.Now().UTC()), |
| 145 | + tag.Host(info.Host)) |
| 146 | + } |
| 147 | + case "DNSDone": |
| 148 | + clientTrace.DNSDone = func(info httptrace.DNSDoneInfo) { |
| 149 | + addresses := make([]string, len(info.Addrs)) |
| 150 | + for i, a := range info.Addrs { |
| 151 | + addresses[i] = a.String() |
| 152 | + } |
| 153 | + logger.Info("finished DNS lookup for Nexus request", |
| 154 | + tag.Timestamp(time.Now().UTC()), |
| 155 | + tag.Addresses(addresses), |
| 156 | + tag.Error(info.Err), |
| 157 | + tag.NewBoolTag("coalesced", info.Coalesced)) |
| 158 | + } |
| 159 | + case "TLSHandshakeStart": |
| 160 | + clientTrace.TLSHandshakeStart = func() { |
| 161 | + logger.Info("starting TLS handshake for Nexus request", tag.Timestamp(time.Now().UTC())) |
| 162 | + } |
| 163 | + case "TLSHandshakeDone": |
| 164 | + clientTrace.TLSHandshakeDone = func(state tls.ConnectionState, err error) { |
| 165 | + logger.Info("finished TLS handshake for Nexus request", |
| 166 | + tag.Timestamp(time.Now().UTC()), |
| 167 | + tag.NewBoolTag("handshake-complete", state.HandshakeComplete), |
| 168 | + tag.Error(err)) |
| 169 | + } |
| 170 | + case "WroteRequest": |
| 171 | + clientTrace.WroteRequest = func(info httptrace.WroteRequestInfo) { |
| 172 | + logger.Info("finished writing Nexus HTTP request", |
| 173 | + tag.Timestamp(time.Now().UTC()), |
| 174 | + tag.Error(info.Err)) |
| 175 | + } |
| 176 | + case "GotFirstResponseByte": |
| 177 | + clientTrace.GotFirstResponseByte = func() { |
| 178 | + logger.Info("got response to Nexus HTTP request", tag.AttemptEnd(time.Now().UTC())) |
| 179 | + } |
| 180 | + } |
| 181 | + } |
| 182 | + return clientTrace |
| 183 | +} |
0 commit comments