|
| 1 | +--- |
| 2 | +title: Логи системных компонентов |
| 3 | +content_type: concept |
| 4 | +weight: 60 |
| 5 | +--- |
| 6 | + |
| 7 | +<!-- overview --> |
| 8 | + |
| 9 | +Логи системных компонентов регистрируют события, происходящие в кластере, что может быть очень полезно при отладке. Степень детализации логов настраивается. Так, в логах низкой детализации будет содержаться только информация об ошибках внутри компонента, в то время как логи высокой детализации будут содержать пошаговую трассировку событий (доступ по HTTP, изменения состояния Pod'а, действия контроллера, решения планировщика). |
| 10 | + |
| 11 | +<!-- body --> |
| 12 | + |
| 13 | +## Klog |
| 14 | + |
| 15 | +[klog](https://github.com/kubernetes/klog) — библиотека Kubernetes для сбора логов. Отвечает за генерацию соответствующих сообщений для системных компонентов оркестратора. |
| 16 | + |
| 17 | +Дополнительные сведения о настройке klog можно получить в [Справке по CLI](/docs/reference/command-line-tools-reference/). |
| 18 | + |
| 19 | +В настоящее время ведется работа по упрощению процесса сбора логов в компонентах Kubernetes. Приведенные ниже флаги командной строки klog [устарели](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2845-deprecate-klog-specific-flags-in-k8s-components), начиная с версии Kubernetes 1.23, и будут удалены в одном из будущих релизов: |
| 20 | + |
| 21 | +- `--add-dir-header` |
| 22 | +- `--alsologtostderr` |
| 23 | +- `--log-backtrace-at` |
| 24 | +- `--log-dir` |
| 25 | +- `--log-file` |
| 26 | +- `--log-file-max-size` |
| 27 | +- `--logtostderr` |
| 28 | +- `--one-output` |
| 29 | +- `--skip-headers` |
| 30 | +- `--skip-log-headers` |
| 31 | +- `--stderrthreshold` |
| 32 | + |
| 33 | +Вывод всегда будет записываться в stderr независимо от его формата. Перенаправление вывода должно осуществляться компонентом, который вызывает компонент Kubernetes, например, POSIX-совместимой командной оболочкой или инструментом вроде systemd. |
| 34 | + |
| 35 | +Иногда эти опции недоступны — например, в случае контейнера без дистрибутива (distroless) или системной службы Windows. Тогда [`kube-log-runner`](https://github.com/kubernetes/kubernetes/blob/d2a8a81639fcff8d1221b900f66d28361a170654/staging/src/k8s.io/component-base/logs/kube-log-runner/README.md) можно использовать в качестве обертки вокруг компонента Kubernetes для перенаправления вывода. Его предварительно собранный исполняемый файл включен в некоторые базовые образы Kubernetes под старым именем `/go-runner`, а в актуальных бинарных релизах архивов с kubernetes-server и kubernetes-node он называется `kube-log-runner`. |
| 36 | + |
| 37 | +В таблице ниже показаны соответствия между вызовами `kube-log-runner` и логикой перенаправления командной оболочки: |
| 38 | + |
| 39 | +| Использование | Оболочка POSIX (например, Bash) | `kube-log-runner <options> <cmd>` | |
| 40 | +| ---------------------------------------------|---------------------------------|---------------------------------------------------------------| |
| 41 | +| Объединить stderr и stdout, вывести в stdout | `2>&1` | `kube-log-runner` (default behavior) | |
| 42 | +| Перенаправить оба потока в файл лога | `1>>/tmp/log 2>&1` | `kube-log-runner -log-file=/tmp/log` | |
| 43 | +| Скопировать в файл лога и в stdout | `2>&1 \| tee -a /tmp/log` | `kube-log-runner -log-file=/tmp/log -also-stdout` | |
| 44 | +| Перенаправить только stdout в файл лога | `>/tmp/log` | `kube-log-runner -log-file=/tmp/log -redirect-stderr=false` | |
| 45 | + |
| 46 | +### Вывод klog |
| 47 | + |
| 48 | +Пример оригинального "родного" формата klog: |
| 49 | +``` |
| 50 | +I1025 00:15:15.525108 1 httplog.go:79] GET /api/v1/namespaces/kube-system/pods/metrics-server-v0.3.1-57c75779f-9p8wg: (1.512ms) 200 [pod_nanny/v0.0.0 (linux/amd64) kubernetes/$Format 10.56.1.19:51756] |
| 51 | +``` |
| 52 | + |
| 53 | +Сообщение может содержать переносы строк: |
| 54 | +``` |
| 55 | +I1025 00:15:15.525108 1 example.go:79] This is a message |
| 56 | +which has a line break. |
| 57 | +``` |
| 58 | + |
| 59 | + |
| 60 | +### Структурированное логирование |
| 61 | + |
| 62 | +{{< feature-state for_k8s_version="v1.23" state="beta" >}} |
| 63 | + |
| 64 | +{{< warning >}} |
| 65 | +Переход на структурированное логирование — продолжающийся процесс. Не все сообщения структурированы в текущей версии Kubernetes. При парсинге файлов логов необходимо также обрабатывать неструктурированные сообщения. |
| 66 | + |
| 67 | +Формат логов и сериализация значений могут измениться в будущем. |
| 68 | +{{< /warning>}} |
| 69 | + |
| 70 | +Структурированное логирование придает определенную структуру сообщениям логов, упрощая программное извлечение информации и сокращая затраты и усилия на их обработку. Код, который генерирует сообщение лога, определяет, используется ли обычный неструктурированный вывод klog или структурированное логирование. |
| 71 | + |
| 72 | +По умолчанию структурированные сообщения форматируются как текст, при этом его формат обратно совместим с традиционным форматом klog: |
| 73 | + |
| 74 | +```ini |
| 75 | +<klog header> "<message>" <key1>="<value1>" <key2>="<value2>" ... |
| 76 | +``` |
| 77 | + |
| 78 | +Пример: |
| 79 | + |
| 80 | +```ini |
| 81 | +I1025 00:15:15.525108 1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready" |
| 82 | +``` |
| 83 | + |
| 84 | +Строки заключаются в кавычки. Другие значения форматируются с помощью [`%+v`](https://pkg.go.dev/fmt#hdr-Printing). В результате сообщение может продолжиться на следующей строке в [зависимости от типа данных](https://github.com/kubernetes/kubernetes/issues/106428). |
| 85 | + |
| 86 | +``` |
| 87 | +I1025 00:15:15.525108 1 example.go:116] "Example" data="This is text with a line break\nand \"quotation marks\"." someInt=1 someFloat=0.1 someStruct={StringField: First line, |
| 88 | +second line.} |
| 89 | +``` |
| 90 | + |
| 91 | +### Контекстное логирование |
| 92 | + |
| 93 | +{{< feature-state for_k8s_version="v1.24" state="alpha" >}} |
| 94 | + |
| 95 | +Контекстное логирование базируется на структурированном логировании. Речь идет в первую очередь о том, как разработчики используют лог-вызовы: код, основанный на этой концепции, более гибок и поддерживает дополнительные сценарии использования (см. [Contextual Logging KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging)). |
| 96 | + |
| 97 | +При использовании в компонентах дополнительных функций, таких как `WithValues` или `WithName`, записи лога содержат дополнительную информацию, которая передается в функции вызывающей стороной. |
| 98 | + |
| 99 | +В настоящее время за включение контекстного логирования отвечает переключатель функционала `StructuredLogging`. По умолчанию оно отключено. Соответствующая инфраструктура появилась в версии 1.24 и она не потребовала изменений в компонентах. Команда [`component-base/logs/example`](https://github.com/kubernetes/kubernetes/blob/v1.24.0-beta.0/staging/src/k8s.io/component-base/logs/example/cmd/logger.go) показывает, как использовать новые лог-вызовы и как ведет себя компонент, поддерживающий контекстное логирование. |
| 100 | + |
| 101 | +```console |
| 102 | +$ cd $GOPATH/src/k8s.io/kubernetes/staging/src/k8s.io/component-base/logs/example/cmd/ |
| 103 | +$ go run . --help |
| 104 | +... |
| 105 | + --feature-gates mapStringBool A set of key=value pairs that describe feature gates for alpha/experimental features. Options are: |
| 106 | + AllAlpha=true|false (ALPHA - default=false) |
| 107 | + AllBeta=true|false (BETA - default=false) |
| 108 | + ContextualLogging=true|false (ALPHA - default=false) |
| 109 | +$ go run . --feature-gates ContextualLogging=true |
| 110 | +... |
| 111 | +I0404 18:00:02.916429 451895 logger.go:94] "example/myname: runtime" foo="bar" duration="1m0s" |
| 112 | +I0404 18:00:02.916447 451895 logger.go:95] "example: another runtime" foo="bar" duration="1m0s" |
| 113 | +``` |
| 114 | + |
| 115 | +Префикс `example` и `foo="bar"` были добавлены вызовом функции, которая пишет в лог сообщение `runtime` и значение `duration="1m0s"`, при этом вносить изменения в эту функцию не потребовалось. |
| 116 | + |
| 117 | +При отключенном контекстном логировании `WithValues` и `WithName` ничего не делают, а вызовы журнала проходят через глобальный логгер klog. Соответственно, эта дополнительная информация более не отображается в логе: |
| 118 | + |
| 119 | +```console |
| 120 | +$ go run . --feature-gates ContextualLogging=false |
| 121 | +... |
| 122 | +I0404 18:03:31.171945 452150 logger.go:94] "runtime" duration="1m0s" |
| 123 | +I0404 18:03:31.171962 452150 logger.go:95] "another runtime" duration="1m0s" |
| 124 | +``` |
| 125 | + |
| 126 | +### Логи в формате JSON |
| 127 | + |
| 128 | +{{< feature-state for_k8s_version="v1.19" state="alpha" >}} |
| 129 | + |
| 130 | +{{<warning >}} |
| 131 | +Вывод в формате JSON не поддерживает многие стандартные флаги klog. Список неподдерживаемых флагов klog см. в [Справочнике по CLI](/docs/reference/command-line-tools-reference/). |
| 132 | + |
| 133 | +Кроме того, запись в формате JSON не гарантируется (например, во время запуска процесса). Таким образом, если планируется дальнейший парсинг логов, убедитесь, что ваш парсер способен обрабатывать строки лога, которые не являются JSON. |
| 134 | + |
| 135 | +Имена полей и сериализация JSON могут измениться в будущем. |
| 136 | +{{< /warning >}} |
| 137 | + |
| 138 | +Флаг `--logging-format=json` переключает формат логов с родного формата klog на JSON. Пример лога в формате JSON (стилистически отформатированном): |
| 139 | +```json |
| 140 | +{ |
| 141 | + "ts": 1580306777.04728, |
| 142 | + "v": 4, |
| 143 | + "msg": "Pod status updated", |
| 144 | + "pod":{ |
| 145 | + "name": "nginx-1", |
| 146 | + "namespace": "default" |
| 147 | + }, |
| 148 | + "status": "ready" |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +Специальные ключи: |
| 153 | +* `ts` — временная метка в формате времени Unix (обязательный параметр, float); |
| 154 | +* `v` — детализация (для общей информации — не для сообщений об ошибках, int); |
| 155 | +* `err` — ошибка (опциональный параметр, string); |
| 156 | +* `msg` — сообщение (обязательный параметр, string). |
| 157 | + |
| 158 | + |
| 159 | +Список компонентов, поддерживающих формат JSON: |
| 160 | +* {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}} |
| 161 | +* {{< glossary_tooltip term_id="kube-apiserver" text="kube-apiserver" >}} |
| 162 | +* {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}} |
| 163 | +* {{< glossary_tooltip term_id="kubelet" text="kubelet" >}} |
| 164 | + |
| 165 | +### Уровень детализации лога |
| 166 | + |
| 167 | +Флаг `-v` задает степень детализации лога. Увеличение значения увеличивает количество регистрируемых событий. Уменьшение значения уменьшает количество регистрируемых событий. Увеличение детализации приводит к тому, что регистрируются все менее значимые события. При уровне детализации, равном 0, регистрируются только критические события. |
| 168 | + |
| 169 | +### Местоположение лога |
| 170 | + |
| 171 | +Существует два типа системных компонентов: те, которые работают в контейнере, и те, которые работают за пределами контейнера. Например: |
| 172 | + |
| 173 | +* Планировщик Kubernetes и kube-proxy работают в контейнере. |
| 174 | +* kubelet и {{<glossary_tooltip term_id="container-runtime" text="среда исполнения для контейнеров">}} |
| 175 | + работают за пределами контейнеров. |
| 176 | + |
| 177 | +На машинах с systemd среда исполнения и kubelet пишут в journald. В противном случае ведется запись в файлы `.log` в директории `/var/log`. Системные компоненты внутри контейнеров всегда пишут в файлы `.log` в директории `/var/log`, обходя механизм логирования по умолчанию. Как и логи контейнеров, логи системных компонентов в `/var/log` нуждаются в ротации. В кластерах Kubernetes, созданных с использованием скрипта `kube-up.sh`, ротация логов настраивается с помощью инструмента `logrotate`. `logrotate` ротирует логи ежедневно или при достижении ими размера в 100 МБ. |
| 178 | + |
| 179 | +## {{% heading "whatsnext" %}} |
| 180 | + |
| 181 | +* [Архитектура логирования в Kubernetes](/docs/concepts/cluster-administration/logging/) |
| 182 | +* [Структурированное логирование (EN)](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging) |
| 183 | +* [Контекстное логирование (EN)](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging) |
| 184 | +* [Вывод флагов klog из эксплуатации (EN)](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2845-deprecate-klog-specific-flags-in-k8s-components) |
| 185 | +* [Соглашения и правила для определения критичности логов (EN)](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md) |
0 commit comments