API do dashboard do Kibana: um contrato estável para todos os tipos de painéis, testado por mais de 50 equipes antes da disponibilidade geral (GA)

Observe, protect, and search your data with a single solution. From application monitoring to threat detection, Kibana is your versatile platform for critical use cases. Start your free 14-day trial now.

As APIs de dashboards e visualizações do Kibana estão prontas para produção no Elastic 9.5, disponíveis em todos os níveis de assinatura, com total compatibilidade com versões anteriores. Defina seus dashboards como JSON, comprometa-os no Git e então implante em ambientes usando pipelines de integração contínua e implantação contínua (CI/CD), Terraform ou qualquer ferramenta que você já tenha. Mais de 50 equipes testaram a API durante a prévia técnica na versão 9.4, algumas já a rodando em produção. A versão 9.5 também adiciona novos endpoints (em prévia técnica) para Tags, com endpoints, dos painéis Markdown e Links disponíveis agora no Elastic Cloud Serverless e chegando na versão 9.6.

O que a compatibilidade com versões anteriores significa para a API do dashboard do Kibana

Durante a prévia técnica, a configuração da API pode mudar entre os lançamentos.[1] Esse não é mais o caso. Disponibilidade geral (GA) significa:

• Compatibilidade retrógrada completa. Novos campos e tipos de painel serão adicionados ao longo do tempo, mas os campos e comportamentos existentes permanecem inalterados. Quaisquer mudanças futuras que quebrem a compatibilidade seriam cuidadosamente consideradas e só seriam introduzidas em uma nova versão principal da pilha.

• Pronto para produção com suporte completo. A API oferece todas as garantias de compatibilidade da Elastic. Você pode usá-lo com segurança em ambientes de produção para implantações automatizadas, promoção de ambiente e gerenciamento programático do dashboard.

Novos endpoints da API Kibana para os painéis Tags, Markdown e Links

O Elastic 9.5 também introduz um novo  endpoint independente para Tags, que permite categorizar e filtrar painéis. Agora, você pode gerenciá-los programaticamente por meio de endpoints CRUD dedicados, facilitando a organização de painéis em escala entre ambientes.

Os novos endpoints para os painéis Markdown e Links já estão disponíveis no Serverless e serão lançados na próxima versão do stack (9.6).

Com quais tipos de painel a API do dashboard do Kibana é compatível?

A API do dashboard é compatível com todos os painéis definidos por valor na versão 9.5 (aqueles definidos diretamente em um dashboard, em oposição aos painéis da biblioteca salvos para reutilização). Cada tipo de painel compatível possui um esquema tipado e validado.

Como gerenciar dashboards do Kibana como código

A API de dashboards permite um fluxo de trabalho completo de dashboards como código: exportar um dashboard como JSON limpo e passível de comparação, enviá-lo ao Git como fonte de verdade, revisar mudanças em pull requests e implantar a mesma definição em desenvolvimento, staging e produção. Depois que um dashboard for gerenciado como código, trate o Git como a única fonte da verdade: as alterações feitas diretamente na UI serão substituídas na próxima vez que você implantar.

O principal desafio ao mover um dashboard entre espaços, clusters ou estágios é que os dashboards referenciam objetos como data view e visualizações da biblioteca por ID. Como esses IDs são gerados automaticamente e diferem entre ambientes, um dashboard exportado de um ambiente pode apontar para objetos que não existem em outro. Existem três maneiras de lidar com isso, listadas aqui da mais automatizada à menos automatizada:

• Use Terraform. O provedor Terraform do Elastic Stack acompanha cada recurso e mapeia os IDs automaticamente por ambiente, para que as referências permaneçam consistentes enquanto você promove um dashboard do desenvolvimento para a produção.

• Defina por-valor a Linguagem de Consulta Elasticsearch (ES|QL). A maneira mais portátil de construir um painel é definir sua visualização com o ES|QL diretamente no dashboard. Uma consulta ES|QL lê os índices que você especificar nela; portanto, o painel não contém referências externas a data views ou objetos de biblioteca. O resultado é um dashboard portátil e totalmente independente.

• Atribua IDs correspondentes. Se você fizer referência a objetos salvos, como visualizações de dados ou visualizações de bibliotecas, crie-os com um ID escolhido usando PUT (upsert) em vez de POST (que gera automaticamente um ID). Use IDs legíveis por humanos, como logs-prod, para que sejam fáceis de reutilizar e reconhecer em diferentes ambientes.

Para obter uma descrição detalhada desses padrões de portabilidade e do fluxo de trabalho completo de dashboards como código, consulte a documentação Gerenciar dashboards como código.

Crie um dashboard do Kibana com a API Dashboards usando PUT

Aqui está um exemplo rápido de criação de um dashboard com uma métrica usando PUT em vez de POST para atribuir um ID personalizado com o nome do dashboard (service-health-overview). A mesma lógica funciona para criar visualizações independentes salvas na biblioteca.

PUT kbn:/api/dashboards/service-health-overview
{
  "título": "Visão geral da saúde do serviço",
  "descrição": "Métricas principais do serviço — gerenciadas via API",
  "tags": [
    "produção",
    "equipe SRE"
  ],
  "painéis": [
    {
      "tipo": "vis",
      "grade": {
        "x": 0,
        "y": 0,
        "w": 12,
        "h": 8
      },
      "config": {
        "título": "Taxa de erro (5xx)",
        "tipo": "métrico",
        "data_source": {
          "type": "esql",
          "query": "FROM logs-* | WHERE http.response.status_code >= 500 | STATS error_rate=count(*) BY host.name"
        },
        "métricas": [
          {
            "type": "primary",
            "column": "count"
          }
        ]
      }
    }
  ]
}

Roadmap da API do dashboard do Kibana: Maps, Vega e endpoints independentes

Estamos expandindo ativamente o escopo da API. Na sequência, compatibilidade com mapas e painéis Vega, adicionando esquemas tipados para eles. Também estamos construindo pontos finais CRUD independentes para sessões Discover (além do suporte existente como painéis de dashboard), Vega, maps e anotações, desacoplados do ciclo de vida do dashboard.

Para as definições completas de esquema, visite a documentação da API dos Dashboards. Para usuários do Terraform, o provedor Terraform do Elastic Stack é compatível com a API GA Dashboards.

Nota

1. Os endpoints núcleos permanecem inalterados em relação à prévia técnica. Se você construiu integrações contra a 9.4, elas funcionam na 9.5. As únicas alterações que quebram a compatibilidade são duas pequenas que afetam os formatos de listagem do dashboard e dos formatos da unidade de duração, documentadas aqui.