Tracing: OpenTracing

До сих пор stringsvc жил в одном процессе, и всех наблюдательных слоёв хватало: лог из урока 06 отвечал «что случилось с этим запросом», метрики из урока 07 — «сколько запросов и как быстро». Но микросервис по определению соседствует с другими сервисами: запрос идёт через балансировщик, транспорт, endpoint, потом улетает в базу или в соседний stringsvc, и уже там что-то ломается. Логи двух сервисов коррелировать нечем: у каждого свой request_id из ServerFinalizer, своя нумерация, свои таймстемпы — склеивать их руками после каждого инцидента невозможно. Метрики дают p90 каждого сервиса по отдельности, но на вопрос «где именно запрос провёл двести миллисекунд» честный ответ — «не знаю, в первом или во втором». Эту слепую зону закрывает распределённый трейсинг: вся операция называется трейсом и имеет один trace id на всю цепочку, а внутри трейса живут спаны — именованные отрезки времени с тегами и событиями: «транспорт принял», «endpoint отработал», «исходящий вызов к соседу занял 180 мс». Подход go kit tracing не изобретает свою модель: go-kit реализует стандарт OpenTracing теми же двумя механизмами, что и логи с метриками, — RequestFunc на транспорте и endpoint.Middleware на endpoint'е. Поэтому к концу урока трейсинг встанет в stringsvc рядом с loggingMiddleware и instrumentingMiddleware, как будто всегда там стоял.

Открой github.com/opentracing/opentracing-go — весь пакет это горстка интерфейсов, и стоит выучить четыре имени. Tracer — фабрика и почтальон: StartSpan(operationName, opts...) создаёт спан, Inject и Extract пакуют и распаковывают контекст трассировки для передачи по сети. Span — отрезок времени: StartSpan возвращает его, span.Finish() фиксирует длительность, SetTag(key, value) вешает метки вроде span.kind=server, LogFields(...) записывает события внутри отрезка. SpanContext — самое хитрое и самое важное: это не сам спан, а минимальные данные для связи спанов между процессами — trace id, id этого спана, решение о сэмплинге; именно SpanContext, а не спан, путешествует по сети. Carrier — конверт, в который SpanContext упаковывается: opentracing.HTTPHeadersCarrier оборачивает http.Header, и Inject пишет туда заголовок uber-trace-id, Extract читает его обратно; помимо HTTPHeaders есть форматы TextMap и Binary, но для веб-сервисов нужен первый. Наконец, ссылки: StartSpan с опцией ChildOf(parent) объявляет, что новый спан — ребёнок родительского, а FollowsFrom — что работа параллельна родителю, например публикация в очередь, на которую мы не ждём ответа. Весь урок ты будешь встречать только ChildOf, но знать оба термина полезно. Правило разбиения простое: одна нога сетевого вызова — один спан; у входящего запроса — server-спан, у исходящего — client-спан, внутри процесса — сколько осмысленных отрезков, столько спанов.

Разберём функцию по строчкам, потому что здесь три решения, которые определяют весь дальнейший трейсинг. Первое — Extract вернёт ошибку opentracing.ErrSpanContextNotFound, если заголовков нет: так будет с самым первым запросом цепочки, от клиента, который ещё не знает о трейсинге. Это не сбой: ext.RPCServerOption(wireContext) спроектирован под оба случая — есть wireContext, и спан станет ChildOf удалённого родителя; нет — и спан станет корнем нового трейса. Транспорт продолжает работать без трейсинга, ничего не падает и не деградирует. Второе — имя операции, второй аргумент HTTPToContext: «HTTP /uppercase» — распространённая конвенция «транспорт + маршрут», по которой в Jaeger UI удобно группировать входящие вызовы; ниже TraceServer создаст второй спан с именем «uppercase» — и дерево сразу читается: транспорт снаружи, endpoint внутри. Третье — почему спан кладётся именно в context.Context, а не в поле request-структуры: endpoint из урока 02 — функция от ctx и request, декодер уже съел http.Request, и единственный канал, который доживает до endpoint-middleware, — это ctx. Тот же контракт ты увидишь в gRPC-транспорте: там инъекцией занимается ContextToGRPC через метаданные gRPC, но идея идентична. Заметь и порядок ServerBefore: HTTPToContext можно ставить первой в списке — ей всё равно, что делают соседи, она читает только http.Request.

Самая ценная деталь TraceEndpoint — работа с ошибками, и она снова про два канала, к которым ты привык с уроков 02 и 05. Если endpoint вернул err != nil — дедлайн, недоступная база, сломанный декодер — middleware записывает в спан стандартное событие ошибки через ext.LogError: в Jaeger такой спан покрасится как ошибочный, и его можно найти фильтром по error-тэгу. Но бизнес-ошибки, как ты помнишь, едут другим путём: адаптер кладёт их в Err-поле response и возвращает err = nil. TraceEndpoint проверяет response на endpoint.Failer: если Failed() вернул не-nil, в спан пишется событие с полем gokit.business.error и текстом ошибки, затем LogError помечает спан как сбойный. Значит, ErrEmpty — честная «пустая строка на входе» — будет видна в Jaeger так же ярко, как отказ базы, хотя транспорт вернул аккуратный 400 из уроков 05. Если для твоего сервиса бизнес-ошибки — норма жизни и шуметь не хочется, включи опцию WithIgnoreBusinessError(true): событие запишется, но спан не покрасится. Отдельная ветка — lb.RetryError из пакета sd/lb: когда endpoint внутри балансировщика, каждая неудачная попытка попадает в спан отдельным полем gokit.retry.error.N — пригодится, когда в уроке 11 будем собирать прокси. Итого: TraceServer уже умеет всё, что ты писал руками в логах, — и сразу привязывает это к trace id.

Параметр Sampler из конфигурации — это решение «трассировать ли вообще», и оно принимается в момент StartSpan: недосэмплированный запрос не создаёт спанов ни у себя, ни у соседей — трейс обрывается тихо, без ошибок. Типов сэмплера в Jaeger четыре, и выбор — вопрос трафика и денег. const с Param 1 или 0 — всё или ничего: единственно правильный вариант для разработки и для малонагруженных внутренних сервисов. probabilistic с Param 0.01 — случайный один процент: стандартная продовая настройка для высоконагруженных сервисов, потому что стоимость растёт линейно с трафиком, а польза от тысяч одинаковых успешных трейсов сомнительна. ratelimiting — не больше N трейсов в секунду: честный потолок нагрузки на инфраструктуру трейсинга. remote — самое взрослое: стратегию присылает агент или collector, и ты меняешь процент выборки в консоли Jaeger, не передеплоивая ни одного сервиса; так и настраивают продовые кластеры. Стоит знать и термин head-based sampling: решение принимается в голове трейса и наследуется всеми спанами — поэтому недосэмплированный запрос нельзя «доотрассировать» потом; противоположность — tail-based sampling, где решение принимают после завершения трейса и хранят только интересные хвосты с ошибками, но это уже работа collector-пайплайна, а не клиента. Начни с const 1, поставь probabilistic, когда трейсинг начнёт жрать заметную долю бюджета — и переведи на remote, когда сервисов станет больше пяти.

Входящая половина готова, но трейс живёт, только когда уезжает вместе с запросом к соседу. Для исходящих у go-kit есть зеркальная пара. ContextToHTTP(tracer, logger) возвращает ту же kithttp.RequestFunc, но для исходящих: она достаёт спан из контекста, проставляет стандартные теги http.method и http.url, достаёт хост с портом в тег peer.hostname и вызывает tracer.Inject(span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(req.Header)) — SpanContext упаковывается в заголовки исходящего http.Request, в тот самый uber-trace-id. Подключается она в клиентском транспорте: httptransport.NewClient(method, target, encodeRequest, decodeResponse, httptransport.ClientBefore(kitot.ContextToHTTP(tracer, logger))) — симметрично ServerBefore из урока 04. А TraceClient(tracer, operationName) — это TraceServer с тегом span.kind=client: оберни ею endpoint, который делает исходящий вызов, и у ноги появится свой отрезок с длительностью. Правило читается само: каждая нога сетевого вызова — client-спан у отправителя и server-спан у получателя; получатель через свой HTTPToContext делает Extract и джойнится к трейсу — Jaeger склеит два сервиса в одно дерево автоматически. Отдельная любопытная деталь: в коде TraceEndpoint есть ветка lb.RetryError — go-kit логирует каждую попытку балансировщика отдельным полем, так что даже ретраи видны в трейсе как события, а не как один серый отрезок.

Открой Jaeger UI на localhost:16686, выбери сервис stringsvc, операцию HTTP /uppercase — и получи список трейсов с гистограммой длительностей. Внутри трейса — дерево: server-спан «HTTP /uppercase» шириной во весь запрос, внутри него дочерний «uppercase» от TraceServer, рядом — client-спаны исходящих вызовов, а у соседа — его server-спан, джойнутый по uber-trace-id. Читать стоит сверху вниз: разница между началом родителя и началом ребёнка — время до endpoint'а, включая декодер и все middleware; ширина ребёнка — время сервиса; промежуток после Finish до конца родителя — время энкодера и сети. Пустой длинный хвост при коротком ребёнке — спрашивай, что происходило в обёртках: ретраи, лимитеры, дедлайны. Фильтр tags=error=true отберёт сбойные трейсы — сюда попадают и инфраструктурные ошибки, и gokit.business.error от Failer, о которых шла речь выше. Практика с логами из урока 06 замыкает петлю: trace_id в логе и в спане — одна и та же строка, поэтому от строки лога ты за один клик попадаешь в трейс, а из трейса — обратно в конкретные строки логов каждого сервиса. Метрики из урока 07 остаются слоем суммарного ответа: p90 говорит, что хвост существует, трейс — где именно он образовался. Три инструмента не дублируют, а дополняют друг друга: метрики — «есть ли проблема», логи — «что случилось», трейс — «где именно по пути».

Четвёртый слой наблюдаемости встал на место: корневой спан инъецируется на транспорте через ServerBefore, TraceServer заводит дочерние спаны на endpoint'ах, ошибки из обоих каналов попадают в трейс, а Jaeger собирает дерево по uber-trace-id. Обещание урока 07 выполнено: спаны связали логи, метрики и теперь ещё и путь запроса одним trace id. Освежить обёртки endpoint — в уроке 02-endpoint, опции транспорта и ServerBefore — в уроке 04-http-transport, структурный лог — в уроке 06-logirovanie, метрики — в уроке 07-metriki; карта курса — на странице курса. Дальше — урок 09-rate-limit: расширенная механика поверх тех же обёрток. Пока весь трафик проходит в сервис свободно, но под нагрузкой или атакой это роскошь: поставим token bucket на endpoint и научимся отвечать честным 429 Too Many Requests с Retry-After.