Componentes importantes para Kubernetes
O OpenTelemetry Collector oferece suporte a muitos receivers e processors diferentes para facilitar o monitoramento do Kubernetes. Esta seção aborda os componentes mais importantes para coletar os dados do Kubernetes e enriquecê-los.
Componentes abordados nesta página:
- Kubernetes Attributes Processor: adiciona metadados do Kubernetes à telemetria recebida da aplicação.
- Kubeletstats Receiver: obtém métricas de nós, pods e contêineres a partir do servidor de API em um kubelet.
- Filelog Receiver: coleta logs do Kubernetes e logs de aplicação escritos em stdout/stderr.
- Kubernetes Cluster Receiver: coleta métricas e eventos de entidade a nível do cluster.
- Kubernetes Objects Receiver: coleta objetos do servidor de API do Kubernetes, como por exemplo eventos.
- Prometheus Receiver: recebe métricas no formato Prometheus.
- Host Metrics Receiver: coleta métricas do host dos nós do Kubernetes.
Para rastros, métricas ou logs de aplicação, recomendamos o OTLP receiver, mas qualquer receiver compatível com seus dados é apropriado.
Kubernetes Attributes Processor
| Padrão de implantação | Utilizável |
|---|---|
| DaemonSet (agente) | Sim |
| Deployment (gateway) | Sim |
| Sidecar | Não |
O Kubernetes Attributes Processor descobre automaticamente os pods do Kubernetes, extrai seus metadados e adiciona esses metadados aos rastros, métricas e logs como atributos de recurso.
O Kubernetes Attributes Processor é um dos componentes mais importantes para um Collector em execução no Kubernetes. Qualquer Collector que receba dados de aplicação deve usá-lo. Ao adicionar contexto do Kubernetes à sua telemetria, o Kubernetes Attributes Processor permite correlacionar os rastros, métricas e logs da sua aplicação com a telemetria do Kubernetes, como métricas e rastros de pods.
O Kubernetes Attributes Processor usa a API do Kubernetes para descobrir todos
os pods em execução em um cluster e mantém um registro de seus endereços IP,
UIDs de pod e outros metadados relevantes. Por padrão, os dados que passam pelo
processor são associados a um pod pelo endereço IP da requisição recebida, mas
é possível configurar outras regras. Como o processor usa a API do Kubernetes,
ele requer permissões especiais (veja o exemplo abaixo). Caso esteja usando o
Helm chart do OpenTelemetry Collector,
é possível usar o
preset kubernetesAttributes
para começar.
Os seguintes atributos são adicionados por padrão:
k8s.namespace.namek8s.pod.namek8s.pod.uidk8s.pod.start_timek8s.deployment.namek8s.node.name
O Kubernetes Attributes Processor também pode definir atributos de recurso personalizados para rastros, métricas e logs usando as labels e as anotações do Kubernetes adicionadas aos pods e namespaces.
k8sattributes:
auth_type: 'serviceAccount'
extract:
metadata: # extraído do pod
- k8s.namespace.name
- k8s.pod.name
- k8s.pod.start_time
- k8s.pod.uid
- k8s.deployment.name
- k8s.node.name
annotations:
# Extrai o valor de uma anotação de pod com a chave `annotation-one` e a insere como um atributo de recurso com a chave `a1`
- tag_name: a1
key: annotation-one
from: pod
# Extrai o valor de uma anotação de namespace com a chave `annotation-two` via regex e a insere como um atributo de recurso com a chave `a2`
- tag_name: a2
key: annotation-two
regex: field=(?P<value>.+)
from: namespace
labels:
# Extrai o valor de um label de namespace com a chave `label1` e o insere como um atributo de recurso com a chave `l1`
- tag_name: l1
key: label1
from: namespace
# Extrai o valor de um label de pod com a chave `label2` via regex e o insere como um atributo de recurso com a chave `l2`
- tag_name: l2
key: label2
regex: field=(?P<value>.+)
from: pod
pod_association: # Como associar os dados a um pod (a ordem importa)
- sources: # Primeiro, tente usar o valor do atributo de recurso k8s.pod.ip
- from: resource_attribute
name: k8s.pod.ip
- sources: # Depois, tente usar o valor do atributo de recurso k8s.pod.uid
- from: resource_attribute
name: k8s.pod.uid
- sources: # Se nenhum dos dois funcionar, use a conexão da requisição para obter o IP do pod.
- from: connection
Também existem opções de configuração especiais para quando o Collector é implantado como um DaemonSet (agente) ou como um Deployment (gateway) do Kubernetes. Para detalhes, veja Cenários de Implantação.
Para detalhes de configuração do Kubernetes Attributes Processor, veja Kubernetes Attributes Processor.
Como o processor usa a API do Kubernetes, ele precisa da permissão correta para funcionar adequadamente. Para a maioria dos casos de uso, é necessário conceder à service account (conta de serviço) que executa o Collector as seguintes permissões por meio de um ClusterRole.
apiVersion: v1
kind: ServiceAccount
metadata:
name: collector
namespace: <OTEL_COL_NAMESPACE>
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: otel-collector
rules:
- apiGroups:
- ''
resources:
- 'pods'
- 'namespaces'
verbs:
- 'get'
- 'watch'
- 'list'
- apiGroups:
- 'apps'
resources:
- 'replicasets'
verbs:
- 'get'
- 'list'
- 'watch'
- apiGroups:
- 'extensions'
resources:
- 'replicasets'
verbs:
- 'get'
- 'list'
- 'watch'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: otel-collector
subjects:
- kind: ServiceAccount
name: collector
namespace: <OTEL_COL_NAMESPACE>
roleRef:
kind: ClusterRole
name: otel-collector
apiGroup: rbac.authorization.k8s.io
Kubeletstats Receiver
| Padrão de implantação | Utilizável |
|---|---|
| DaemonSet (agente) | Preferível |
| Deployment (gateway) | Sim, mas coletará métricas somente do nó em que está implantado |
| Sidecar | Não |
Cada nó do Kubernetes executa um kubelet que inclui um servidor de API. O Kubeletstats Receiver se conecta a esse kubelet por meio do servidor de API para coletar métricas sobre o nó e as cargas de trabalho em execução nele.
Existem diferentes métodos de autenticação, mas normalmente se usa uma conta de
serviço. A conta de serviço também precisará das permissões adequadas para obter
dados do Kubelet (veja abaixo). Caso estiver usando o
Helm chart do OpenTelemetry Collector,
é possível usar o
preset kubeletMetrics
para começar.
Por padrão, as métricas são coletadas para pods e nós, mas é possível configurar o receiver para coletar também métricas de contêiner e de volume. O receiver também permite configurar a frequência de coleta das métricas:
receivers:
kubeletstats:
collection_interval: 10s
auth_type: 'serviceAccount'
endpoint: '${env:K8S_NODE_NAME}:10250'
insecure_skip_verify: true
metric_groups:
- node
- pod
- container
Para detalhes específicos sobre quais métricas são coletadas, veja Métricas padrão. Para detalhes de configuração específicos, veja Kubeletstats Receiver.
Como o processor usa a API do Kubernetes, ele precisa da permissão correta para funcionar. Para a maioria dos casos de uso, é necessário conceder à conta de serviço que executa o Collector as seguintes permissões por meio de um ClusterRole.
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: otel-collector
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: otel-collector
rules:
- apiGroups: ['']
resources: ['nodes/stats']
verbs: ['get', 'watch', 'list']
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: otel-collector
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: otel-collector
subjects:
- kind: ServiceAccount
name: otel-collector
namespace: default
Filelog Receiver
| Padrão de implantação | Utilizável |
|---|---|
| DaemonSet (agente) | Preferível |
| Deployment (gateway) | Sim, mas coletará logs somente do nó em que está implantado |
| Sidecar | Sim, mas isso seria considerado uma configuração avançada |
O Filelog Receiver acompanha (tail) e analisa (parse) logs a partir de arquivos. Embora não seja um receiver específico para Kubernetes, ainda é a solução de fato para coletar qualquer log do Kubernetes.
O Filelog Receiver é composto por Operadores encadeados entre si para processar
um log. Cada Operador tem uma responsabilidade simples, como analisar um
timestamp ou um JSON. Configurar um Filelog Receiver não é trivial. Caso
esteja usando o
Helm chart do OpenTelemetry Collector,
é possível usar o
preset logsCollection
para começar.
Como os logs do Kubernetes normalmente seguem um conjunto de formatos padrão, uma configuração típica de Filelog Receiver para Kubernetes se parece com o seguinte:
file_log:
include:
- /var/log/pods/*/*/*.log
exclude:
# Exclui logs de todos os contêineres chamados otel-collector
- /var/log/pods/*/otel-collector/*.log
start_at: end
include_file_path: true
include_file_name: false
operators:
# analisa os logs do contêiner
- type: container
id: container-parser
Para detalhes de configuração do Filelog Receiver, veja Filelog Receiver.
Além da configuração do Filelog Receiver, sua instalação do OpenTelemetry Collector no Kubernetes precisará de acesso aos logs que deseja coletar. Normalmente isso significa adicionar alguns volumes e volumeMounts ao manifesto do seu Collector:
---
apiVersion: apps/v1
kind: DaemonSet
...
spec:
...
template:
...
spec:
...
containers:
- name: opentelemetry-collector
...
volumeMounts:
...
# Monta os volumes no contêiner do Collector
- name: varlogpods
mountPath: /var/log/pods
readOnly: true
- name: varlibdockercontainers
mountPath: /var/lib/docker/containers
readOnly: true
...
volumes:
...
# Normalmente o Collector precisa de acesso aos logs de pods e de contêineres
- name: varlogpods
hostPath:
path: /var/log/pods
- name: varlibdockercontainers
hostPath:
path: /var/lib/docker/containers
...
Kubernetes Cluster Receiver
| Padrão de implantação | Utilizável |
|---|---|
| DaemonSet (agente) | Sim, mas resultará em dados duplicados |
| Deployment (gateway) | Sim, mas mais de uma réplica resulta em dados duplicados |
| Sidecar | Não |
O Kubernetes Cluster Receiver coleta métricas e eventos de entidade sobre o cluster como um todo, usando o servidor de API do Kubernetes. Use esse receiver para responder perguntas sobre fases de pods, condições de nós e outras questões a nível de cluster. Como o receiver reúne telemetria para o cluster como um todo, basta uma instância do receiver em todo o cluster para coletar todos os dados.
Existem diferentes métodos de autenticação, mas normalmente se usa uma conta de
serviço. A conta de serviço também precisa das permissões adequadas para obter
dados do servidor de API do Kubernetes (veja abaixo). Caso esteja usando o
Helm chart do OpenTelemetry Collector,
é possível usar o
preset clusterMetrics
para começar.
Para condições de nós, o receiver coleta apenas Ready por padrão, mas ele
pode ser configurado para coletar mais condições. O receiver também pode ser
configurado para reportar um conjunto de recursos alocáveis, como cpu e
memory:
k8s_cluster:
auth_type: serviceAccount
node_conditions_to_report:
- Ready
- MemoryPressure
allocatable_types_to_report:
- cpu
- memory
Para saber mais sobre as métricas coletadas, veja Métricas padrão. Para detalhes de configuração, veja Kubernetes Cluster Receiver.
Como o processor usa a API do Kubernetes, ele precisa da permissão correta para funcionar. Para a maioria dos casos de uso, é necessário conceder à conta de serviço que executa o Collector as seguintes permissões por meio de um ClusterRole.
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: otel-collector-opentelemetry-collector
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: otel-collector-opentelemetry-collector
rules:
- apiGroups:
- ''
resources:
- events
- namespaces
- namespaces/status
- nodes
- nodes/spec
- pods
- pods/status
- replicationcontrollers
- replicationcontrollers/status
- resourcequotas
- services
verbs:
- get
- list
- watch
- apiGroups:
- apps
resources:
- daemonsets
- deployments
- replicasets
- statefulsets
verbs:
- get
- list
- watch
- apiGroups:
- extensions
resources:
- daemonsets
- deployments
- replicasets
verbs:
- get
- list
- watch
- apiGroups:
- batch
resources:
- jobs
- cronjobs
verbs:
- get
- list
- watch
- apiGroups:
- autoscaling
resources:
- horizontalpodautoscalers
verbs:
- get
- list
- watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: otel-collector-opentelemetry-collector
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: otel-collector-opentelemetry-collector
subjects:
- kind: ServiceAccount
name: otel-collector-opentelemetry-collector
namespace: default
Kubernetes Objects Receiver
| Padrão de implantação | Utilizável |
|---|---|
| DaemonSet (agente) | Sim, mas resultará em dados duplicados |
| Deployment (gateway) | Sim, mas mais de uma réplica resulta em dados duplicados |
| Sidecar | Não |
O Kubernetes Objects Receiver coleta, por pulling ou por watching, objetos do servidor de API do Kubernetes. O caso de uso mais comum para esse receiver é observar (watching) eventos do Kubernetes, mas ele pode ser usado para coletar qualquer tipo de objeto do Kubernetes. Como o receiver reúne telemetria para o cluster como um todo, basta uma instância do receiver em todo o cluster para coletar todos os dados.
Atualmente, apenas uma conta de serviço pode ser usada para autenticação. A
conta de serviço também precisa das permissões adequadas para obter dados do
servidor de API do Kubernetes (veja abaixo). Caso esteja usando o
Helm chart do OpenTelemetry Collector
para ingerir eventos, é possível usar o
preset kubernetesEvents
para começar.
Para objetos configurados para pulling, o receiver usa a API do Kubernetes para listar periodicamente todos os objetos no cluster. Cada objeto é convertido em seu próprio log. Para objetos configurados para watching, o receiver cria um stream com a API do Kubernetes, que recebe atualizações conforme os objetos mudam.
Para ver quais objetos estão disponíveis para coleta no seu cluster, execute
kubectl api-resources:
kubectl api-resources
NAME SHORTNAMES APIVERSION NAMESPACED KIND
bindings v1 true Binding
componentstatuses cs v1 false ComponentStatus
configmaps cm v1 true ConfigMap
endpoints ep v1 true Endpoints
events ev v1 true Event
limitranges limits v1 true LimitRange
namespaces ns v1 false Namespace
nodes no v1 false Node
persistentvolumeclaims pvc v1 true PersistentVolumeClaim
persistentvolumes pv v1 false PersistentVolume
pods po v1 true Pod
podtemplates v1 true PodTemplate
replicationcontrollers rc v1 true ReplicationController
resourcequotas quota v1 true ResourceQuota
secrets v1 true Secret
serviceaccounts sa v1 true ServiceAccount
services svc v1 true Service
mutatingwebhookconfigurations admissionregistration.k8s.io/v1 false MutatingWebhookConfiguration
validatingwebhookconfigurations admissionregistration.k8s.io/v1 false ValidatingWebhookConfiguration
customresourcedefinitions crd,crds apiextensions.k8s.io/v1 false CustomResourceDefinition
apiservices apiregistration.k8s.io/v1 false APIService
controllerrevisions apps/v1 true ControllerRevision
daemonsets ds apps/v1 true DaemonSet
deployments deploy apps/v1 true Deployment
replicasets rs apps/v1 true ReplicaSet
statefulsets sts apps/v1 true StatefulSet
tokenreviews authentication.k8s.io/v1 false TokenReview
localsubjectaccessreviews authorization.k8s.io/v1 true LocalSubjectAccessReview
selfsubjectaccessreviews authorization.k8s.io/v1 false SelfSubjectAccessReview
selfsubjectrulesreviews authorization.k8s.io/v1 false SelfSubjectRulesReview
subjectaccessreviews authorization.k8s.io/v1 false SubjectAccessReview
horizontalpodautoscalers hpa autoscaling/v2 true HorizontalPodAutoscaler
cronjobs cj batch/v1 true CronJob
jobs batch/v1 true Job
certificatesigningrequests csr certificates.k8s.io/v1 false CertificateSigningRequest
leases coordination.k8s.io/v1 true Lease
endpointslices discovery.k8s.io/v1 true EndpointSlice
events ev events.k8s.io/v1 true Event
flowschemas flowcontrol.apiserver.k8s.io/v1beta2 false FlowSchema
prioritylevelconfigurations flowcontrol.apiserver.k8s.io/v1beta2 false PriorityLevelConfiguration
ingressclasses networking.k8s.io/v1 false IngressClass
ingresses ing networking.k8s.io/v1 true Ingress
networkpolicies netpol networking.k8s.io/v1 true NetworkPolicy
runtimeclasses node.k8s.io/v1 false RuntimeClass
poddisruptionbudgets pdb policy/v1 true PodDisruptionBudget
clusterrolebindings rbac.authorization.k8s.io/v1 false ClusterRoleBinding
clusterroles rbac.authorization.k8s.io/v1 false ClusterRole
rolebindings rbac.authorization.k8s.io/v1 true RoleBinding
roles rbac.authorization.k8s.io/v1 true Role
priorityclasses pc scheduling.k8s.io/v1 false PriorityClass
csidrivers storage.k8s.io/v1 false CSIDriver
csinodes storage.k8s.io/v1 false CSINode
csistoragecapacities storage.k8s.io/v1 true CSIStorageCapacity
storageclasses sc storage.k8s.io/v1 false StorageClass
volumeattachments storage.k8s.io/v1 false VolumeAttachment
Para detalhes específicos de configuração, veja Kubernetes Objects Receiver.
Como o processor usa a API do Kubernetes, ele precisa da permissão correta para funcionar. Como contas de serviço são a única opção de autenticação, é necessário conceder à conta de serviço o acesso adequado. Para cada objeto que quiser coletar, é preciso garantir que o nome dele esteja adicionado ao cluster role. Por exemplo, para coletar pods, o cluster role ficaria assim:
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: otel-collector-opentelemetry-collector
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: otel-collector-opentelemetry-collector
rules:
- apiGroups:
- ''
resources:
- pods
verbs:
- get
- list
- watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: otel-collector-opentelemetry-collector
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: otel-collector-opentelemetry-collector
subjects:
- kind: ServiceAccount
name: otel-collector-opentelemetry-collector
namespace: default
Prometheus Receiver
| Padrão de implantação | Utilizável |
|---|---|
| DaemonSet (agente) | Sim |
| Deployment (gateway) | Sim |
| Sidecar | Não |
O Prometheus é um formato de métricas comum tanto para o Kubernetes quanto para
serviços em execução nele. O receiver do Prometheus é um substituto mínimo
para a coleta dessas métricas. Ele suporta o conjunto completo de
opções do scrape_config
do Prometheus.
Existem alguns recursos avançados do Prometheus que o receiver não suporta. O receiver retorna um erro se o YAML/código de configuração contiver algum dos seguintes itens:
alert_config.alertmanagersalert_config.relabel_configsremote_readremote_writerule_files
Para detalhes de configuração específicos, veja Prometheus Receiver.
O Prometheus receiver é Stateful, o que significa que existem detalhes importantes a considerar ao usá-lo:
- O Collector não consegue escalar automaticamente o processo de scraping quando múltiplas réplicas do Collector são executadas.
- Ao executar múltiplas réplicas do Collector com a mesma configuração, ele fará o scraping dos destinos (targets) múltiplas vezes.
- Os usuários precisam configurar cada réplica com uma configuração de scraping diferente caso queiram fazer o particionamento (sharding) manual do processo de scraping.
Para facilitar a configuração do Prometheus receiver, o OpenTelemetry Operator inclui um componente opcional chamado Target Allocator. Esse componente pode ser usado para informar a um Collector quais endpoints do Prometheus ele deve fazer o scraping.
Para mais informações sobre o design do receiver, veja Design.
Host Metrics Receiver
| Padrão de implantação | Utilizável |
|---|---|
| DaemonSet (agente) | Preferível |
| Deployment (gateway) | Sim, mas coleta métricas somente do nó em que está implantado |
| Sidecar | Não |
O Host Metrics Receiver coleta métricas de um host usando diversos scrapers. Há alguma sobreposição com o Kubeletstats Receiver, então, ao usar os dois, pode valer a pena desabilitar essas métricas duplicadas.
No Kubernetes, o receiver precisa de acesso ao volume hostfs para funcionar
corretamente. Caso esteja usando o
Helm chart do OpenTelemetry Collector,
é possível usar o
preset hostMetrics
para começar.
Os scrapers disponíveis são:
| Scraper | SOs com suporte | Descrição |
|---|---|---|
| cpu | Todos, exceto macOS1 | Métricas de utilização de CPU |
| disk | Todos, exceto macOS1 | Métricas de E/S de disco |
| load | Todos | Métricas de carga de CPU |
| filesystem | Todos | Métricas de utilização do sistema de arquivos |
| memory | Todos | Métricas de utilização de memória |
| network | Todos | Métricas de E/S de interface de rede e de conexão TCP |
| paging | Todos | Métricas de utilização e E/S de paging/espaço de swap |
| processes | Linux, macOS | Métricas de contagem de processos |
| process | Linux, macOS, Windows | Métricas de CPU, memória e E/S de disco por processo |
Para detalhes específicos sobre quais métricas são coletadas e detalhes de configuração específicos, veja Host Metrics Receiver.
Caso precise configurar o componente manualmente, não se esqueça de montar o
volume hostfs para coletar as métricas do nó, e não do contêiner.
---
apiVersion: apps/v1
kind: DaemonSet
...
spec:
...
template:
...
spec:
...
containers:
- name: opentelemetry-collector
...
volumeMounts:
...
- name: hostfs
mountPath: /hostfs
readOnly: true
mountPropagation: HostToContainer
volumes:
...
- name: hostfs
hostPath:
path: /
...
e então configure o Host Metrics Receiver para usar o volumeMount:
receivers:
host_metrics:
root_path: /hostfs
collection_interval: 10s
scrapers:
cpu:
load:
memory:
disk:
filesystem:
network:
Para mais detalhes sobre como usar o receiver dentro de um contêiner, veja Coletando métricas de host de dentro de um contêiner (somente Linux).
Feedback
Esta página foi útil?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!