Acessar e usar registros da plataforma

Configure os registros da plataforma no Artifact Registry para ver informações sobre solicitações bem-sucedidas e com falha feitas aos repositórios do Artifact Registry. Os registros da plataforma são gerados pelo Cloud Logging e podem ser vistos no Análise de registros. É possível analisar os registros da plataforma do Artifact Registry para ajudar a resolver problemas de solicitações com falha, manter registros de solicitações bem-sucedidas e conferir o número de downloads de um artefato.

Um registro da plataforma é formatado como um LogEntry.

Visão geral

O Artifact Registry gera registros da plataforma para chamadas de API do plano de dados e do plano de controle. As ações do plano de controle incluem operações de gerenciamento de repositórios, como criação, edição de descrições e exclusão de repositórios, e ações de gerenciamento de artefatos, como listagem, inclusão de tags e exclusão de artefatos. As ações do plano de dados incluem operações como envio e extração de artefatos de repositórios do Artifact Registry.

Os registros dos dois tipos de chamadas contêm as seguintes informações:

Detalhes da solicitação
Detalhes da resposta
Status
Rótulos
- Nome do método
- Nome do recurso
- Local do recurso
- ID da operação (para operações de longa duração)
- Formato do repositório (para recursos do repositório)
- Modo de repositório (para recursos de repositório)

Além disso, os registros de chamadas de API do plano de controle contêm as seguintes informações:

Informações HTTP
- Método de solicitação
- URL de solicitação
- Tamanho da solicitação (em bytes)
- Status
- Tamanho da resposta (em bytes)
- User agent
- IP remoto (IP do cliente que emitiu a solicitação)
- Protocolo
- Referenciador
- Latência

É possível conferir os registros da plataforma do Artifact Registry na Análise de registros.

Antes de começar

Ative a API Logging.

Funções exigidas

Para receber as permissões necessárias para gerenciar registros da plataforma, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Administrador do Artifact Registry (roles/artifactregistry.admin)
Leitor do Logging (roles/logging.viewer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar a geração de registros da plataforma

É possível ativar o registro da plataforma em todo o projeto Google Cloud ou em um repositório específico.

Ativar a geração de registros da plataforma para um projeto

Para ativar o registro da plataforma no projeto do Google Cloud , execute o seguinte comando:

CLI da gcloud

gcloud artifacts projects update --enable-platform-logs --severity=SEVERITY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH -H "X-GFE-SSL: yes" -H "Content-Type: application/json" -d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {"logging_state": "ENABLED", "severity_level": "SEVERITY"}}' "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Em que:

SEVERITY determina o tipo de ações que acionam a criação de registros da plataforma do Artifact Registry. É possível inserir INFO, ERROR ou excluir o campo --severity para criar registros da plataforma para todas as ações compatíveis.
LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

Ativar a geração de registros da plataforma para um repositório

CLI da gcloud

gcloud artifacts repositories update --enable-platform-logs --severity=SEVERITY REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {"loggingState": "ENABLED", "severityLevel": "SEVERITY"}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Em que:

SEVERITY determina o tipo de ações que acionam a criação de registros da plataforma do Artifact Registry. É possível inserir INFO, ERROR ou excluir o campo --severity para criar registros da plataforma para todas as ações compatíveis.
REPOSITORY é o nome do seu repositório no Artifact Registry.
LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

Verificar a configuração da geração de registros da plataforma

É possível verificar se o registro da plataforma do Artifact Registry está ativado no seu projeto ou em um repositório específico.

Verificar o registro da plataforma para um projeto

Para verificar se o registro da plataforma do Artifact Registry está ativado no seu projeto, execute o seguinte comando:

CLI da gcloud

gcloud artifacts projects describe --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Em que:

LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

O resultado será o seguinte:

{
  "name": "projects/PROJECT/locations/{"<var>LOCATION</var>"}}/projectConfig"
  "platformLogsConfig": {
    "loggingState": "ENABLED"
    "severityLevel": "INFO"
  }
}

Verificar o registro da plataforma para um repositório

Para verificar se o registro de plataforma do Artifact Registry está ativado em um repositório, execute o seguinte comando:

CLI da gcloud

gcloud artifacts repositories describe REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY"

Em que:

REPOSITORY é o nome do repositório;
LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

O resultado será o seguinte:

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY"
  "platformLogsConfig": {
    "loggingState": "ENABLED",
    "severityLevel": "INFO"
  }
}

Desativar a geração de registros da plataforma

É possível desativar o registro em plataforma para todo o projeto Google Cloud ou para um repositório específico.

Desativar a geração de registros da plataforma para um projeto

Para desativar o registro da plataforma no seu projeto Google Cloud , execute o seguinte comando:

CLI da gcloud

gcloud artifacts projects update --disable-platform-logs --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {"logging_state": "DISABLED"}}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Em que:

LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

Desativar a geração de registros da plataforma para um repositório

Para desativar o registro em plataforma de um repositório, execute o seguinte comando:

CLI da gcloud

gcloud artifacts repositories update --disable-platform-logs REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {"loggingState": "DISABLED", "severityLevel": "INFO"}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Em que:

REPOSITORY é o nome do seu repositório no Artifact Registry.
LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

Limpar a configuração de geração de registros da plataforma

É possível limpar a configuração de geração de registros da plataforma para um projeto ou um repositório. Quando você executa o comando de limpeza, o loggingState e o severityLevel do projeto ou repositório são definidos como nulos.

Se você limpar a configuração do projeto, somente os repositórios em que o registro da plataforma já foi ativado vão gerar registros da plataforma. Se você limpar a configuração de um repositório, ele vai herdar a configuração de geração de registros da plataforma do seu projeto.

Limpar a configuração de geração de registros da plataforma para um projeto

Para limpar a configuração de geração de registros da plataforma do seu projeto Google Cloud , execute o seguinte comando:

CLI da gcloud

gcloud artifacts projects update --clear-platform-logs --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {}}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Em que:

LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

Limpar a configuração de geração de registros da plataforma para um repositório

Para limpar a configuração de geração de registros da plataforma de um repositório, execute o seguinte comando:

CLI da gcloud

gcloud artifacts repositories update --clear-platform-logs REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Em que:

REPOSITORY é o nome do seu repositório no Artifact Registry.
LOCATION é o local do repositório.
PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

Ver registros da plataforma

Para conferir os registros da plataforma, faça o seguinte:

Abra a página da Análise de registros no console do Google Cloud .

Abrir a página da Análise de registros
No painel de consultas, clique no menu suspenso Nome do registro.
Insira requests e marque a caixa de seleção requests no cabeçalho Artifact Registry.
Clique em Aplicar.

O Logging mostra registros de chamadas de API do plano de dados e do plano de controle no painel Resultados da consulta.
Para ver o conteúdo de um registro, clique na seta ao lado de qualquer registro listado nos resultados da consulta.

Para mais informações sobre como entender os resultados da consulta na Análise de registros, consulte Ver os resultados da consulta.

Analisar registros da plataforma com a Análise de observabilidade

Use a Análise de observabilidade para executar consultas SQL nos registros do Artifact Registry e analisar os registros com mais detalhes. Esta seção contém vários exemplos de consultas para casos de uso comuns. É possível adaptar essas consultas para analisar outros aspectos do uso do Artifact Registry filtrando diferentes campos na estrutura LogEntry.

Antes de começar a usar a análise de observabilidade, faça o seguinte:

Configure seus buckets de registros para usar a Análise de observabilidade.
Configure papéis e permissões do Identity and Access Management para usar o Observability Analytics.

Em seguida, siga as etapas para Inserir e executar uma consulta personalizada. Quando você chegar ao painel Consulta do SQL, insira uma das seguintes consultas de exemplo:

Exemplo: os 10 principais endereços IP por volume de downloads

Essa consulta avalia os registros da plataforma do Artifact Registry e retorna os 10 principais endereços IP que baixaram mais dados dos seus repositórios nos últimos sete dias:

SELECT
  http_request.remote_ip AS client_ip,
  SUM(http_request.response_size) AS total_download_bytes
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND http_request.request_method = "GET"
  AND http_request.status >= 200 AND http_request.status < 300
  AND http_request.response_size > 0
  AND CAST(http_request.response_size AS INT64) > 0
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY
  client_ip
ORDER BY
  total_download_bytes DESC
LIMIT 10;

Exemplo: solicitações por repositório

Essa consulta avalia os registros da plataforma do Artifact Registry e retorna o número de solicitações feitas a cada repositório nas últimas 24 horas:

SELECT
  JSON_VALUE(resource.labels.repository_id) AS repository,
  JSON_VALUE(resource.labels.location) AS location,
  COUNT(*) AS request_count
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
GROUP BY
  repository,
  location
ORDER BY
  request_count DESC;

Exemplo: solicitações com falha

Essa consulta avalia os registros da plataforma do Artifact Registry e lista detalhes das 10 solicitações com falha mais recentes na última hora:

SELECT
  timestamp,
  http_request.status,
  http_request.request_method,
  http_request.request_url,
  http_request.remote_ip,
  JSON_VALUE(resource.labels.repository_id) AS repository,
  JSON_VALUE(labels.resource_name) AS artifact_name,
  trace
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND http_request.status >= 400
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
ORDER BY
  timestamp DESC
LIMIT 10;

Acessar e usar registros da plataforma Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Antes de começar

Funções exigidas

Ativar a geração de registros da plataforma

Ativar a geração de registros da plataforma para um projeto

CLI da gcloud

curl

Ativar a geração de registros da plataforma para um repositório

CLI da gcloud

curl

Verificar a configuração da geração de registros da plataforma

Verificar o registro da plataforma para um projeto

CLI da gcloud

curl

Verificar o registro da plataforma para um repositório

CLI da gcloud

curl

Desativar a geração de registros da plataforma

Desativar a geração de registros da plataforma para um projeto

CLI da gcloud

curl

Desativar a geração de registros da plataforma para um repositório

CLI da gcloud

curl

Limpar a configuração de geração de registros da plataforma

Limpar a configuração de geração de registros da plataforma para um projeto

CLI da gcloud

curl

Limpar a configuração de geração de registros da plataforma para um repositório

CLI da gcloud

curl

Ver registros da plataforma

Analisar registros da plataforma com a Análise de observabilidade

Exemplo: os 10 principais endereços IP por volume de downloads

Exemplo: solicitações por repositório

Exemplo: solicitações com falha

Acessar e usar registros da plataforma