# Підтримка нативних гістограм для метрик Kubernetes

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->








  <div class="feature-state-notice feature-alpha" title="Функціональна можливість: NativeHistograms">
              <span class="feature-state-name">СТАН ФУНКЦІОНАЛУ:</span> 
              <code>Kubernetes v1.36 [alpha]</code>(стандартно вимкнено)</div>


Компоненти Kubernetes можуть експонувати метрики гістограм у форматі [Prometheus Native Histogram](https://prometheus.io/docs/specs/native_histograms/), поряд із класичним форматом гістограм. Нативні гістограми використовують експоненційні межі кошиків замість фіксованих меж, що забезпечує значну ефективність зберігання, покращену продуктивність запитів та більш детальне відображення розподілів.

<!-- body -->

## Перш ніж почати {#before-you-begin}

Щоб використовувати нативні гістограми, вам потрібно мати:

- **Kubernetes v1.36 або новішу версію** з увімкненою функціональною можливістю [`NativeHistograms`](/docs/reference/command-line-tools-reference/feature-gates/#NativeHistograms).
- **Prometheus 2.40 або новішу версію** для збору та зберігання нативних гістограм. Рекомендується Prometheus 3.0+ для конфігурації на рівні завдань.

## Що таке нативні гістограми? {#what-are-native-histograms}

Класичні гістограми Prometheus використовують фіксовані межі кошиків (наприклад, `[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]` секунд). Кожен кошик створює окрему часову серію (`_bucket`, `_count`, `_sum`), що може призвести до:

- **Високих витрат на зберігання** у великих масштабах, оскільки кожна гістограма генерує багато часових серій.
- **Проблем з точністю**, оскільки дані в межах широкого кошика є невідрізненими. Наприклад, запит, що виконується за 1 мкс, і запит, що виконується за 4 мс, обидва потрапляють у той самий кошик `le="0.005"`.

[Нативні гістограми](https://prometheus.io/docs/specs/native_histograms/) вирішують ці обмеження, використовуючи експоненційні межі кошиків, які автоматично підлаштовуються під розподіл даних. Переваги включають:

- **~10x зменшення кількості часових серій** для кожної метрики гістограми, що значно зменшує обсяг зберігання Prometheus і покращує продуктивність запитів.
- **Більш детальна роздільна здатність** для виявлення регресій продуктивності та встановлення точних порогів SLO.

## Як це працює {#how-it-works}

Коли функціональна можливість `NativeHistograms` увімкнена, компоненти Kubernetes одночасно експонують метрики гістограм у класичному та нативному форматах (подвійна експозиція). Формат, що повертається, залежить від заголовка `Accept` у HTTP-запиті ([узгодження вмісту Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/#content-negotiation)). Prometheus автоматично встановлює цей заголовок на основі вашої конфігурації збору; вам потрібно враховувати це лише при безпосередньому запиті до точки доступу `/metrics`.

- **Текстовий формат** (Accept: `text/plain`, OpenMetrics 1.0): Повертає лише класичні кошики гістограм. Зворотно сумісний з усіма наявними інструментами.

  ```text
  # Classic histogram buckets (always present)
  apiserver_request_duration_seconds_bucket{le="0.005"} 1000
  apiserver_request_duration_seconds_bucket{le="0.01"} 2000
  ...
  apiserver_request_duration_seconds_bucket{le="+Inf"} 10000
  apiserver_request_duration_seconds_count 10000
  apiserver_request_duration_seconds_sum 450.5
  ```

- **Формат Protobuf** (Accept: `application/vnd.google.protobuf`): Містить як класичні кошики, так і дані нативних гістограм. Prometheus автоматично запитує цей формат, коли `scrape_native_histograms: true` встановлено в [конфігурації збору Prometheus](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) для відповідного завдання збору.

Ця стратегія подвійної експозиції забезпечує:

- Наявні інфопанелі та сповіщення продовжують працювати без змін.
- Користувачі можуть поступово переносити запити на нативні гістограми.
- Prometheus зберігає той формат, який він налаштований збирати.

## Увімкнення нативних гістограм {#enabling-native-histograms}

Увімкнення нативних гістограм є двоетапним процесом: увімкніть функціональну можливість на компонентах Kubernetes і налаштуйте Prometheus для збору нативних гістограм.

### Крок 1: Увімкніть функціональну можливість Kubernetes {#step-1-enable-the-kubernetes-feature-gate}

Увімкніть функціональну можливість `NativeHistograms` на компонентах Kubernetes, з яких ви хочете експонувати нативні гістограми:

```bash
--feature-gates=NativeHistograms=true
```

Ця функціональна можливість застосовується до наступних компонентів:

- kube-apiserver
- kube-controller-manager
- kube-scheduler
- kubelet
- kube-proxy

Метрики кожного компонента є незалежними; ви можете увімкнути або вимкнути функціональну можливість для кожного компонента окремо.

### Крок 2: Налаштуйте Prometheus {#step-2-configure-prometheus}

Конфігурація Prometheus залежить від вашої версії Prometheus.

| Версія Prometheus | Підтримка нативних гістограм | Конфігурація                                                             | Примітки                                                                        |
| ------------------ | ------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| < 2.40             | Немає                     | N/A                                                                       | Тільки класичні гістограми. Увімкнення функціональної можливості Kubernetes не має ефекту. |
| 2.40 – 2.x         | Експериментальна             | `--enable-feature=native-histograms` (глобально)                             | Все або нічого; немає контролю на рівні завдання.                                          |
| 3.0 – 3.7          | Стабільна                   | На рівні завдання `scrape_native_histograms` та `always_scrape_classic_histograms` | Рекомендовано конфігурацію на рівні завдання. Глобальний прапорець все ще підтримується.              |
| 3.8                | Стабільна                   | Конфігурація на рівні завдання (необхідна для точного контролю)                 | Глобальний прапорець лише змінює значення за замовчуванням для всіх завдань.                               |
| 3.9+               | Стабільна                   | На рівні завдання `scrape_native_histograms` тільки                                   | Глобальний прапорець видалено. Потрібно використовувати конфігурацію на рівні завдання.                         |

Для Prometheus 3.x використовуйте конфігурацію на рівні завдання для точного контролю:

```yaml
scrape_configs:
  - job_name: 'kubernetes-apiservers'
    scrape_native_histograms: true            # Використовує нативні гістограми
    always_scrape_classic_histograms: true    # Зберігає класичний формат під час міграції
```

Встановіть обидві опції в `true` під час періоду міграції. Це дозволяє збирати нативні гістограми, зберігаючи класичні гістограми для наявних інформаційних панелей.


<div class="alert alert-info" role="note"><h4 class="alert-heading">Примітка:</h4>Нативні гістограми вимагають формату експозиції Protobuf. Це обробляється автоматично Prometheus за замовчуванням. Однак, якщо ви налаштували <code>scrape_protocols</code>, переконайтеся, що <code>PrometheusProto</code> включено до списку.</div>


## Міграція інформаційних панелей та сповіщень {#migrating-dashboards-and-alerts}

<div class="alert alert-caution" role="note"><h4 class="alert-heading">Увага:</h4>Якщо Prometheus налаштовано з <code>scrape_native_histograms: true</code>, але <code>always_scrape_classic_histograms: false</code> (стандартно), Prometheus збирає лише нативні гістограми. Наявні інформаційні панелі, які використовують класичні запити гістограм (наприклад, <code>histogram_quantile(..._bucket...)</code>), не відображатимуть дані. Завжди встановлюйте <code>always_scrape_classic_histograms: true</code> під час міграції.</div>


Під час міграції з класичних запитів гістограм на нативні гістограми, дотримуйтесь цього робочого процесу:

1. **Увімкніть обидва формати**: Встановіть `scrape_native_histograms: true` та `always_scrape_classic_histograms: true` у конфігурації збору Prometheus.

2. **Міграція запитів**: Оновіть запити інформаційних панелей та вирази сповіщень з класичних функцій гістограм на еквіваленти нативних гістограм.

   Класичний запит:

   ```promql
   histogram_quantile(0.99, rate(apiserver_request_duration_seconds_bucket[5m]))
   ```

   Запит для нативних гістограм:

   ```promql
   histogram_quantile(0.99, rate(apiserver_request_duration_seconds[5m]))
   ```

3. **Перевірка на staging**: Перевірте всі інформаційні панелі та сповіщення з запитами нативних гістограм перед впровадженням в експлуатацію.

4. **Вимкнення класичного збору**: Після завершення та перевірки міграції встановіть `always_scrape_classic_histograms: false`, щоб зменшити обсяг зберігання.

## Вимкнення нативних гістограм {#disabling-native-histograms}

Ви можете вимкнути нативні гістограми в будь-який час, використовуючи один із двох підходів:

- **На стороні Prometheus (найшвидший, не потребує перезапуску Kubernetes; тільки Prometheus 3.x)**: Встановіть `scrape_native_histograms: false` для кожного завдання збору. Prometheus відновлює збір класичного формату на наступному інтервалі збору.

- **Функціональна можливість Kubernetes**: Перезапустіть компонент з `--feature-gates=NativeHistograms=false`. Після перезапуску буде доступний тільки класичний формат гістограм.

Коли нативні гістограми вимкнено, точка доступу метрик повертається до класичного формату гістограм. Історичні дані нативних гістограм у Prometheus залишаються доступними для запитів.

## Усунення несправностей {#troubleshooting}

- **Інформаційні панелі не відображають дані після увімкнення нативних гістограм**: Це відбувається, коли Prometheus налаштовано з `scrape_native_histograms: true`, але `always_scrape_classic_histograms: false` (зазвичай), і ваші інформаційні панелі все ще використовують класичні запити гістограм (наприклад, `histogram_quantile(..._bucket...)`).

  Виправлення: Встановіть `always_scrape_classic_histograms: true`, щоб відновити збір класичного формату під час міграції інформаційних панелей.

- **Збільшення використання памʼяті після увімкнення нативних гістограм**: Невелике збільшення памʼяті очікується для зберігання кошиків нативних гістограм, обмежене максимумом 160 кошиків на гістограму. Відстежуйте `process_resident_memory_bytes` для виявлення несподіваних збільшень.

  Виправлення: Якщо тиск на памʼять значний, вимкніть збір нативних гістограм у Prometheus (`scrape_native_histograms: false`) або вимкніть функціональну можливість Kubernetes.

- **Логи Prometheus повідомляють про невідомий формат метрик**: Ваша версія Prometheus занадто стара, щоб розуміти нативні гістограми.

  Виправлення: Оновіть Prometheus до версії 2.40+ або вимкніть нативні гістограми в Kubernetes.

- **Не впевнені, чи нативні гістограми експонуються**: Перевірте стан функціональної можливості, виконавши запит `kubernetes_feature_enabled{name="NativeHistograms"}` у Prometheus. Значення `1` вказує на те, що функціональна можливість увімкнена. Ви також можете безпосередньо запитати кінцеву точку метрик у форматі protobuf:

  ```bash
  curl -H "Accept: application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited" \
    https://<component-address>/metrics
  ```

  Відповідь повинна містити кодування нативних гістограм для метрик гістограм.

## Посилання {#references}

- Прочитайте [документацію Prometheus про нативні гістограми](https://prometheus.io/docs/specs/native_histograms/) для отримання деталей про формат нативних гістограм та функції запитів.
- Див. [довідник метрик Kubernetes](/docs/reference/instrumentation/metrics/) для повного списку метрик, які експонуються компонентами Kubernetes.