# Recuperar métricas com a API do Insights de Performance do Amazon RDS
Quando o Insights de Performance está ativado, a API oferece visibilidade à performance da instância. O Amazon CloudWatch Logs fornece a fonte de autorização para métricas de monitoramento fornecidas para serviços da AWS.
O Performance Insights oferece uma visão específica do domínio da carga do banco de dados medida como sessões ativas médias (AAS). Essa métrica aparece para os consumidores de API como um conjunto de dados bidimensional de séries temporais. A dimensão de tempo dos dados fornece a carga do banco de dados para cada ponto de tempo no intervalo de tempo consultado. Cada ponto de tempo decompõe a carga geral em relação às dimensões solicitadas, como `SQL`, `Wait-event`, `User` ou `Host`, medidas naquele ponto de tempo.
O Amazon RDS Performance Insights monitora o cluster Amazon RDS da instância de banco de dados , para que você possa analisar e solucionar problemas relacionados à performance do banco de dados. Uma maneira de visualizar os dados do Performance Insights está no Console de gerenciamento da AWS. O Performance Insights também fornece uma API pública para que você possa consultar seus próprios dados. É possível usar a API para fazer o seguinte:
+ Descarregar dados em um banco de dados
+ Adicione dados do Performance Insights aos painéis de monitoramento existentes
+ Criar ferramentas de monitoramento
Para usar a API do Performance Insights, habilite o Performance Insights em uma das suas instâncias de banco de dados do Amazon RDS. Para obter informações sobre como habilitar o Performance Insights, consulte [Ativar e desativar o Insights de Performance do Amazon RDS](USER_PerfInsights.Enabling.md). Para obter mais informações sobre a API do Performance Insights, consulte a [Referência de API do Amazon RDS Performance Insights](https://docs.aws.amazon.com/performance-insights/latest/APIReference/Welcome.html).
A API do Performance Insights fornece as operações a seguir.
****
| Ação do Performance Insights | AWS CLI command | Descrição |
| --- | --- | --- |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_CreatePerformanceAnalysisReport.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_CreatePerformanceAnalysisReport.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/CreatePerformanceAnalysisReport.html](https://docs.aws.amazon.com/cli/latest/reference/pi/CreatePerformanceAnalysisReport.html) | Cria um relatório de análise de performance referente a um período específico para a instância de banco de dados. O resultado é `AnalysisReportId`, que é o identificador exclusivo do relatório. |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DeletePerformanceAnalysisReport.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DeletePerformanceAnalysisReport.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/DeletePerformanceAnalysisReport.html](https://docs.aws.amazon.com/cli/latest/reference/pi/DeletePerformanceAnalysisReport.html) | Exclui um relatório de análise de performance. |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DescribeDimensionKeys.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DescribeDimensionKeys.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/describe-dimension-keys.html](https://docs.aws.amazon.com/cli/latest/reference/pi/describe-dimension-keys.html) | Recuperar as N principais chaves de dimensão de uma métrica por um período específico. |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetDimensionKeyDetails.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetDimensionKeyDetails.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/get-dimension-key-details.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-dimension-key-details.html) | Recupera os atributos do grupo de dimensões especificado para uma instância de banco de dados ou fonte de dados. Por exemplo, se você especificar um ID SQL e se os detalhes da dimensão estiverem disponíveis, `GetDimensionKeyDetails` recuperará o texto completo da dimensão `db.sql.statement` associada a esse ID. Essa operação é útil porque `GetResourceMetrics` e `DescribeDimensionKeys` não oferecem suporte à recuperação de texto grande de instrução SQL. |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetPerformanceAnalysisReport.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetPerformanceAnalysisReport.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/GetPerformanceAnalysisReport.html](https://docs.aws.amazon.com/cli/latest/reference/pi/GetPerformanceAnalysisReport.html) | Recupera o relatório, incluindo os insights do relatório. O resultado inclui o status do relatório, o ID do relatório, os detalhes do horário do relatório, os insights e as recomendações. |
| [GetResourceMetadata](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetResourceMetadata.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metadata.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metadata.html) | Recupere os metadados para diferentes recursos. Por exemplo, os metadados podem indicar que um recurso está ativado ou desativado em uma instância de banco de dados específica. |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetResourceMetrics.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetResourceMetrics.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html) | Recupera as métricas do Performance Insights para um conjunto de fontes de dados, ao longo de um período. É possível fornecer grupos de dimensão e dimensões específicos e fornecer critérios de filtragem e agregação para cada grupo. |
| [ListAvailableResourceDimensions](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListAvailableResourceDimensions.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-dimensions.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-dimensions.html) | Recupere as dimensões que podem ser consultadas para cada tipo de métrica especificado em uma instância especificada. |
| [ListAvailableResourceMetrics](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListAvailableResourceMetrics.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-metrics.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-metrics.html) | Recupere todas as métricas disponíveis dos tipos de métrica especificados que podem ser consultados para uma instância de banco de dados especificada. |
| `[ListPerformanceAnalysisReports](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListPerformanceAnalysisReports.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-performance-analysis-reports.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-performance-analysis-reports.html) | Recupera todos os relatórios de análise disponíveis para a instância de banco de dados. Os relatórios são listados com base na hora de início de cada relatório. |
| `[ListTagsForResource](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListTagsForResource.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-tags-for-resource.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-tags-for-resource.html) | Lista todas as tags de metadados adicionadas ao recurso. A lista inclui o nome e o valor da tag. |
| `[TagResource](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_TagResource.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/tag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/pi/tag-resource.html) | Adiciona tags de metadados ao recurso do Amazon RDS. A tag inclui um nome e um valor. |
| `[UntagResource](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_UntagResource.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/untag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/pi/untag-resource.html) | Remove a tag de metadados do recurso. |
Para ter mais informações sobre como recuperar métricas de séries temporais e exemplos da AWS CLI para o Insights de Performance, consulte os tópicos a seguir.
**Topics**
+ [Recuperar métricas de séries temporais do Insights de Performance](USER_PerfInsights.API.TimeSeries.md)
+ [Exemplos da AWS CLI para o Performance Insights](USER_PerfInsights.API.Examples.md)
# Recuperar métricas de séries temporais do Insights de Performance
A operação `GetResourceMetrics` recupera uma ou mais métricas de séries temporais dos dados do Performance Insights. `GetResourceMetrics` requer uma métrica e um período de tempo e retorna uma resposta com uma lista de pontos de dados.
Por exemplo, o Console de gerenciamento da AWS usa `GetResourceMetrics` para preencher o gráfico **Métricas de contador** e o gráfico **Carregamento do banco de dados**, como visto na imagem a seguir.
![\[Gráficos Counter Metrics e Database Load\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/perf-insights-api-charts.png)
Todas as métricas retornadas por `GetResourceMetrics` são métricas de séries temporais padrão, com exceção de `db.load`. Essa métrica é exibida no gráfico **Carregamento do banco de dados**. A métrica `db.load` é diferente das outras métricas da série temporal, pois você pode fragmentá-la em subcomponentes chamados de *dimensões*. Na imagem anterior, `db.load` é dividido e agrupado pelos estados de espera que compõem o `db.load`.
**nota**
`GetResourceMetrics` também pode retornar a métrica `db.sampleload`, mas a métrica `db.load` é apropriada na maioria dos casos.
Para obter informações sobre as métricas de contador retornadas pelo `GetResourceMetrics`, consulte [Métricas de contadores do Performance Insights](USER_PerfInsights_Counters.md).
Os cálculos a seguir são compatíveis com as métricas:
+ Média: o valor médio para a métrica por um período. Adicione `.avg` ao nome da métrica.
+ Mínimo: o valor mínimo para a métrica por um período. Adicione `.min` ao nome da métrica.
+ Máximo: o valor máximo para a métrica por um período. Adicione `.max` ao nome da métrica.
+ Soma: a soma dos valores da métrica por um período. Adicione `.sum` ao nome da métrica.
+ Contagem de amostra: o número de vezes que a métrica foi coletada por um período. Adicione `.sample_count` ao nome da métrica.
Por exemplo, considere que uma métrica é coletada por 300 segundos (5 minutos) e que a métrica seja coletada uma vez por minuto. Os valores de cada minuto são 1, 2, 3, 4 e 5. Nesse caso, os seguintes cálculos são retornados:
+ Média: 3
+ Mínimo: 1
+ Máximo: 5
+ Soma: 15
+ Contagem de amostras: 5
Para obter informações sobre como usar o comando `get-resource-metrics` AWS CLI, consulte [https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html).
Para a opção `--metric-queries`, especifique uma ou mais consultas para as quais deseja obter resultados. Cada consulta consiste em um parâmetro obrigatório `Metric` e opcional `GroupBy` e em parâmetros `Filter`. Veja a seguir um exemplo de uma especificação de opção `--metric-queries`.
```
{
"Metric": "string",
"GroupBy": {
"Group": "string",
"Dimensions": ["string", ...],
"Limit": integer
},
"Filter": {"string": "string"
...}
```
# Exemplos da AWS CLI para o Performance Insights
Nas seções a seguir, saiba mais sobre a AWS Command Line Interface (AWS CLI) para o Insights de Performance e use exemplos da AWS CLI.
**Topics**
+ [Ajuda integrada da AWS CLI para o Insights de Performance](#USER_PerfInsights.API.CLI)
+ [Recuperar métricas de contador](#USER_PerfInsights.API.Examples.CounterMetrics)
+ [Recuperar a média de carga de banco de dados para eventos de espera superior](#USER_PerfInsights.API.Examples.DBLoadAverage)
+ [Recuperar a média de carga de banco de dados para SQL principal](#USER_PerfInsights.API.Examples.DBLoadAverageTop10SQL)
+ [Recuperação da média de carga de banco de dados filtrada por SQL](#USER_PerfInsights.API.Examples.DBLoadAverageFilterBySQL)
+ [Recuperar o texto completo de uma instrução SQL](#USER_PerfInsights.API.Examples.GetDimensionKeyDetails)
+ [Criar um relatório de análise de performance para um período](#USER_PerfInsights.API.Examples.CreatePerfAnalysisReport)
+ [Recuperar um relatório de análise de performance](#USER_PerfInsights.API.Examples.GetPerfAnalysisReport)
+ [Listar todos os relatórios de análise de performance da instância de banco de dados](#USER_PerfInsights.API.Examples.ListPerfAnalysisReports)
+ [Excluir um relatório de análise de performance](#USER_PerfInsights.API.Examples.DeletePerfAnalysisReport)
+ [Adicionar tags a um relatório de análise de performance](#USER_PerfInsights.API.Examples.TagPerfAnalysisReport)
+ [Listar todas as tags para um relatório de análise de performance](#USER_PerfInsights.API.Examples.ListTagsPerfAnalysisReport)
+ [Excluir tags de um relatório de análise de performance](#USER_PerfInsights.API.Examples.UntagPerfAnalysisReport)
## Ajuda integrada da AWS CLI para o Insights de Performance
É possível visualizar dados do Performance Insights usando o AWS CLI. É possível visualizar a ajuda dos comandos da AWS CLI para o Performance Insights, inserindo o seguinte na linha de comando.
```
aws pi help
```
Se você não tiver a AWS CLI instalada, consulte informações sobre como instalá-la em [Instalar a AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) no *Guia do usuário da AWS CLI*.
## Recuperar métricas de contador
A captura de tela a seguir mostra dois gráficos de métricas de contador no Console de gerenciamento da AWS.
![\[Gráficos de métricas de contador.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/perf-insights-api-counters-charts.png)
O exemplo a seguir mostra como reunir os mesmos dados que o Console de gerenciamento da AWS usa para gerar os dois gráficos de métricas de contador.
Para Linux, macOS ou Unix:
```
aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries '[{"Metric": "os.cpuUtilization.user.avg" },
{"Metric": "os.cpuUtilization.idle.avg"}]'
```
Para Windows:
```
aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^
--period-in-seconds 60 ^
--metric-queries '[{"Metric": "os.cpuUtilization.user.avg" },
{"Metric": "os.cpuUtilization.idle.avg"}]'
```
Você também pode tornar um comando mais fácil de ler, especificando um arquivo para a opção `--metrics-query`. O exemplo a seguir usa um arquivo chamado query.json para a opção. O arquivo tem o seguinte conteúdo.
```
[
{
"Metric": "os.cpuUtilization.user.avg"
},
{
"Metric": "os.cpuUtilization.idle.avg"
}
]
```
Execute o seguinte comando para usar o arquivo.
Para Linux, macOS ou Unix:
```
aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries file://query.json
```
Para Windows:
```
aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^
--period-in-seconds 60 ^
--metric-queries file://query.json
```
O exemplo anterior especifica os seguintes valores para as opções:
+ `--service-type`: `RDS` para Amazon RDS
+ `--identifier` – O ID do recurso para a instância do banco de dados
+ `--start-time` e `--end-time` – Os valores ISO 8601 de `DateTime` para o período a consultar, com vários formatos compatíveis
Ele consulta um intervalo de tempo de uma hora:
+ `--period-in-seconds` – `60` para uma consulta por minuto
+ `--metric-queries` – uma matriz de duas consultas, cada uma apenas para uma métrica.
O nome da métrica usa pontos para classificar a métrica em uma categoria útil, com o elemento final sendo uma função. No exemplo, a função é `avg` para cada consulta. Como no Amazon CloudWatch, as funções com suporte são `min`, `max`, `total` e `avg`.
A resposta é semelhante à seguinte.
```
{
"Identifier": "db-XXX",
"AlignedStartTime": 1540857600.0,
"AlignedEndTime": 1540861200.0,
"MetricList": [
{ //A list of key/datapoints
"Key": {
"Metric": "os.cpuUtilization.user.avg" //Metric1
},
"DataPoints": [
//Each list of datapoints has the same timestamps and same number of items
{
"Timestamp": 1540857660.0, //Minute1
"Value": 4.0
},
{
"Timestamp": 1540857720.0, //Minute2
"Value": 4.0
},
{
"Timestamp": 1540857780.0, //Minute 3
"Value": 10.0
}
//... 60 datapoints for the os.cpuUtilization.user.avg metric
]
},
{
"Key": {
"Metric": "os.cpuUtilization.idle.avg" //Metric2
},
"DataPoints": [
{
"Timestamp": 1540857660.0, //Minute1
"Value": 12.0
},
{
"Timestamp": 1540857720.0, //Minute2
"Value": 13.5
},
//... 60 datapoints for the os.cpuUtilization.idle.avg metric
]
}
] //end of MetricList
} //end of response
```
A resposta tem `Identifier`, `AlignedStartTime` e `AlignedEndTime`. Se o valor de `--period-in-seconds` fosse `60`, as horas de início e término seriam alinhadas ao minuto. Se `--period-in-seconds` fosse `3600`, as horas de início e término teriam sido alinhadas à hora.
O `MetricList` na resposta tem um número de entradas, cada uma com uma entrada `Key` e `DataPoints`. Cada `DataPoint` tem um `Timestamp` e um `Value`. Cada lista `Datapoints` tem 60 pontos de dados, pois as consultas são para dados por minuto ao longo de uma hora, com `Timestamp1/Minute1`, `Timestamp2/Minute2` e assim por diante, até `Timestamp60/Minute60`.
Como a consulta é para duas métricas de contador diferentes, há dois elementos na resposta `MetricList`.
## Recuperar a média de carga de banco de dados para eventos de espera superior
O exemplo a seguir é a mesma consulta que o Console de gerenciamento da AWS usa para gerar um gráfico de linha de área empilhada. Este exemplo recupera o `db.load.avg` para a última hora com carga dividida de acordo com os sete principais eventos de espera. O comando é o mesmo que o comando em [Recuperar métricas de contador](#USER_PerfInsights.API.Examples.CounterMetrics). No entanto, o arquivo query.json tem o seguinte conteúdo.
```
[
{
"Metric": "db.load.avg",
"GroupBy": { "Group": "db.wait_event", "Limit": 7 }
}
]
```
Execute o comando a seguir.
Para Linux, macOS ou Unix:
```
aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries file://query.json
```
Para Windows:
```
aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^
--period-in-seconds 60 ^
--metric-queries file://query.json
```
O exemplo especifica a métrica de `db.load.avg` e um `GroupBy` dos sete principais eventos de espera. Para obter detalhes sobre valores válidos para esse exemplo, consulte [DimensionGroup](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DimensionGroup.html) na *Referência de API do Performance Insights.*
A resposta é semelhante à seguinte.
```
{
"Identifier": "db-XXX",
"AlignedStartTime": 1540857600.0,
"AlignedEndTime": 1540861200.0,
"MetricList": [
{ //A list of key/datapoints
"Key": {
//A Metric with no dimensions. This is the total db.load.avg
"Metric": "db.load.avg"
},
"DataPoints": [
//Each list of datapoints has the same timestamps and same number of items
{
"Timestamp": 1540857660.0, //Minute1
"Value": 0.5166666666666667
},
{
"Timestamp": 1540857720.0, //Minute2
"Value": 0.38333333333333336
},
{
"Timestamp": 1540857780.0, //Minute 3
"Value": 0.26666666666666666
}
//... 60 datapoints for the total db.load.avg key
]
},
{
"Key": {
//Another key. This is db.load.avg broken down by CPU
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.name": "CPU",
"db.wait_event.type": "CPU"
}
},
"DataPoints": [
{
"Timestamp": 1540857660.0, //Minute1
"Value": 0.35
},
{
"Timestamp": 1540857720.0, //Minute2
"Value": 0.15
},
//... 60 datapoints for the CPU key
]
},
//... In total we have 8 key/datapoints entries, 1) total, 2-8) Top Wait Events
] //end of MetricList
} //end of response
```
Nessa resposta, há oito entradas no `MetricList`. Há uma entrada para o total `db.load.avg`, e sete entradas cada para o `db.load.avg`, divididas de acordo com um dos sete principais eventos de espera. Ao contrário do primeiro exemplo, como havia uma dimensão de agrupamento, deve haver uma chave para cada agrupamento da métrica. Não pode haver apenas uma chave para cada métrica, como no caso de uso de métricas de contador.
## Recuperar a média de carga de banco de dados para SQL principal
O exemplo a seguir agrupa `db.wait_events` pelas 10 principais instruções SQL. Existem dois grupos diferentes para instruções SQL:
+ `db.sql` – a instrução SQL completa, como `select * from customers where customer_id = 123`
+ `db.sql_tokenized` – a instrução SQL tokenizada, como `select * from customers where customer_id = ?`
Ao analisar a performance do banco de dados, pode ser útil considerar instruções SQL que diferem apenas por seus parâmetros como um item lógico. Então, você pode usar `db.sql_tokenized` ao consultar. No entanto, especialmente quando você está interessado em explicar planos, às vezes é mais útil examinar instruções SQL completas com parâmetros e agrupamentos de consulta por `db.sql`. Existe um relacionamento pai-filho entre o SQL tokenizado e o SQL completo, com vários SQL completos (filhos) agrupados sob o mesmo SQL (pai) tokenizado.
O comando neste exemplo é semelhante ao comando em [Recuperar a média de carga de banco de dados para eventos de espera superior](#USER_PerfInsights.API.Examples.DBLoadAverage). No entanto, o arquivo query.json tem o seguinte conteúdo.
```
[
{
"Metric": "db.load.avg",
"GroupBy": { "Group": "db.sql_tokenized", "Limit": 10 }
}
]
```
O exemplo a seguir usa `db.sql_tokenized`.
Para Linux, macOS ou Unix:
```
aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-29T00:00:00Z \
--end-time 2018-10-30T00:00:00Z \
--period-in-seconds 3600 \
--metric-queries file://query.json
```
Para Windows:
```
aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-29T00:00:00Z ^
--end-time 2018-10-30T00:00:00Z ^
--period-in-seconds 3600 ^
--metric-queries file://query.json
```
Este exemplo consulta mais de 24 horas, com um período de uma hora em segundos.
O exemplo especifica a métrica de `db.load.avg` e um `GroupBy` dos sete principais eventos de espera. Para obter detalhes sobre valores válidos para esse exemplo, consulte [DimensionGroup](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DimensionGroup.html) na *Referência de API do Performance Insights.*
A resposta é semelhante à seguinte.
```
{
"AlignedStartTime": 1540771200.0,
"AlignedEndTime": 1540857600.0,
"Identifier": "db-XXX",
"MetricList": [ //11 entries in the MetricList
{
"Key": { //First key is total
"Metric": "db.load.avg"
}
"DataPoints": [ //Each DataPoints list has 24 per-hour Timestamps and a value
{
"Value": 1.6964980544747081,
"Timestamp": 1540774800.0
},
//... 24 datapoints
]
},
{
"Key": { //Next key is the top tokenized SQL
"Dimensions": {
"db.sql_tokenized.statement": "INSERT INTO authors (id,name,email) VALUES\n( nextval(?) ,?,?)",
"db.sql_tokenized.db_id": "pi-2372568224",
"db.sql_tokenized.id": "AKIAIOSFODNN7EXAMPLE"
},
"Metric": "db.load.avg"
},
"DataPoints": [ //... 24 datapoints
]
},
// In total 11 entries, 10 Keys of top tokenized SQL, 1 total key
] //End of MetricList
} //End of response
```
Essa resposta tem 11 entradas no `MetricList` (1 total, 10 principais SQLs tokenizados), com cada entrada com 24 `DataPoints` por hora.
Para o SQL tokenizado, existem três entradas em cada lista de dimensões:
+ `db.sql_tokenized.statement` – a instrução SQL tokenizada.
+ `db.sql_tokenized.db_id ` – o ID do banco de dados nativo usado para referência ao SQL ou um ID sintético que o Performance Insights gera para você quando o ID do banco de dados nativo não está disponível. Este exemplo retorna o ID sintético `pi-2372568224`.
+ `db.sql_tokenized.id` – o ID da consulta dentro do Performance Insights.
No Console de gerenciamento da AWS, esse ID é chamado de ID de suporte. Ele é chamado assim porque o ID consiste em dados que o AWS Support pode examinar para ajudar você a solucionar um problema no banco de dados. A AWS leva a segurança e privacidade de seus dados extremamente a sério, e quase todos os dados são armazenados criptografados com a chave do AWS KMS. Portanto, ninguém dentro da AWS pode examinar esses dados. No exemplo precedente, `tokenized.statement` e `tokenized.db_id` são armazenados em formato criptografado. Se você tiver um problema com o banco de dados, o Suporte da AWS poderá ajudar você consultando o ID de suporte.
Ao consultar, pode ser conveniente especificar `Group` em `GroupBy`. No entanto, para um controle mais refinado sobre os dados retornados, especifique a lista de dimensões. Por exemplo, se tudo o que for necessário for o `db.sql_tokenized.statement`, um atributo `Dimensions` poderá ser adicionado ao arquivo query.json.
```
[
{
"Metric": "db.load.avg",
"GroupBy": {
"Group": "db.sql_tokenized",
"Dimensions":["db.sql_tokenized.statement"],
"Limit": 10
}
}
]
```
## Recuperação da média de carga de banco de dados filtrada por SQL
![\[Filtrar por gráfico SQL.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/UserGuide/images/perf-insights-api-filter-chart.png)
A imagem anterior mostra que uma consulta específica está selecionada e que o gráfico de linhas da área empilhada das sessões ativas da média superior tem o escopo para essa consulta. Embora a consulta ainda seja para os sete principais eventos de espera geral, o valor da resposta é filtrado. O filtro faz com que ele leve em consideração apenas as sessões correspondentes ao filtro específico.
A consulta da API correspondente neste exemplo é semelhante ao comando em [Recuperar a média de carga de banco de dados para SQL principal](#USER_PerfInsights.API.Examples.DBLoadAverageTop10SQL). No entanto, o arquivo query.json tem o seguinte conteúdo.
```
[
{
"Metric": "db.load.avg",
"GroupBy": { "Group": "db.wait_event", "Limit": 5 },
"Filter": { "db.sql_tokenized.id": "AKIAIOSFODNN7EXAMPLE" }
}
]
```
Para Linux, macOS ou Unix:
```
aws pi get-resource-metrics \
--service-type RDS \
--identifier db-ID \
--start-time 2018-10-30T00:00:00Z \
--end-time 2018-10-30T01:00:00Z \
--period-in-seconds 60 \
--metric-queries file://query.json
```
Para Windows:
```
aws pi get-resource-metrics ^
--service-type RDS ^
--identifier db-ID ^
--start-time 2018-10-30T00:00:00Z ^
--end-time 2018-10-30T01:00:00Z ^
--period-in-seconds 60 ^
--metric-queries file://query.json
```
A resposta é semelhante à seguinte.
```
{
"Identifier": "db-XXX",
"AlignedStartTime": 1556215200.0,
"MetricList": [
{
"Key": {
"Metric": "db.load.avg"
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 1.4878117913832196
},
{
"Timestamp": 1556222400.0,
"Value": 1.192823803967328
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "io",
"db.wait_event.name": "wait/io/aurora_redo_log_flush"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 1.1360544217687074
},
{
"Timestamp": 1556222400.0,
"Value": 1.058051341890315
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "io",
"db.wait_event.name": "wait/io/table/sql/handler"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.16241496598639457
},
{
"Timestamp": 1556222400.0,
"Value": 0.05163360560093349
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "synch",
"db.wait_event.name": "wait/synch/mutex/innodb/aurora_lock_thread_slot_futex"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.11479591836734694
},
{
"Timestamp": 1556222400.0,
"Value": 0.013127187864644107
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "CPU",
"db.wait_event.name": "CPU"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.05215419501133787
},
{
"Timestamp": 1556222400.0,
"Value": 0.05805134189031505
}
]
},
{
"Key": {
"Metric": "db.load.avg",
"Dimensions": {
"db.wait_event.type": "synch",
"db.wait_event.name": "wait/synch/mutex/innodb/lock_wait_mutex"
}
},
"DataPoints": [
{
"Timestamp": 1556218800.0,
"Value": 0.017573696145124718
},
{
"Timestamp": 1556222400.0,
"Value": 0.002333722287047841
}
]
}
],
"AlignedEndTime": 1556222400.0
} //end of response
```
Nessa resposta, todos os valores são filtrados de acordo com a contribuição de SQL tokenizado AKIAIOSFODNN7EXAMPLE especificado no arquivo query.json. As chaves também podem seguir uma ordem diferente de uma consulta sem um filtro, porque são os cinco principais eventos de espera que afetaram o SQL filtrado.
## Recuperar o texto completo de uma instrução SQL
O exemplo a seguir recupera o texto completo de uma instrução SQL para a instância de banco de dados `db-10BCD2EFGHIJ3KL4M5NO6PQRS5`. O `--group` é `db.sql`, e o `--group-identifier` é `db.sql.id`. Nesse exemplo, *my-sql-id* representa um ID SQL recuperado que invoca `pi get-resource-metrics` ou `pi describe-dimension-keys`.
Execute o comando a seguir.
Para Linux, macOS ou Unix:
```
aws pi get-dimension-key-details \
--service-type RDS \
--identifier db-10BCD2EFGHIJ3KL4M5NO6PQRS5 \
--group db.sql \
--group-identifier my-sql-id \
--requested-dimensions statement
```
Para Windows:
```
aws pi get-dimension-key-details ^
--service-type RDS ^
--identifier db-10BCD2EFGHIJ3KL4M5NO6PQRS5 ^
--group db.sql ^
--group-identifier my-sql-id ^
--requested-dimensions statement
```
Nesse exemplo, os detalhes das dimensões estão disponíveis. Assim, o Performance Insights recupera o texto completo da instrução SQL, sem truncá-lo.
```
{
"Dimensions":[
{
"Value": "SELECT e.last_name, d.department_name FROM employees e, departments d WHERE e.department_id=d.department_id",
"Dimension": "db.sql.statement",
"Status": "AVAILABLE"
},
...
]
}
```
## Criar um relatório de análise de performance para um período
O exemplo a seguir cria um relatório de análise de performance com o horário de início `1682969503` e o horário de término `1682979503` do banco de dados `db-loadtest-0`.
```
aws pi create-performance-analysis-report \
--service-type RDS \
--identifier db-loadtest-0 \
--start-time 1682969503 \
--end-time 1682979503 \
--region us-west-2
```
A resposta é o identificador exclusivo `report-0234d3ed98e28fb17` do relatório.
```
{
"AnalysisReportId": "report-0234d3ed98e28fb17"
}
```
## Recuperar um relatório de análise de performance
O exemplo a seguir recupera os detalhes do relatório de análise do relatório `report-0d99cc91c4422ee61`.
```
aws pi get-performance-analysis-report \
--service-type RDS \
--identifier db-loadtest-0 \
--analysis-report-id report-0d99cc91c4422ee61 \
--region us-west-2
```
A resposta fornece o status, o ID, os detalhes do horário e os insights do relatório.
```
{
"AnalysisReport": {
"Status": "Succeeded",
"ServiceType": "RDS",
"Identifier": "db-loadtest-0",
"StartTime": 1680583486.584,
"AnalysisReportId": "report-0d99cc91c4422ee61",
"EndTime": 1680587086.584,
"CreateTime": 1680587087.139,
"Insights": [
... (Condensed for space)
]
}
}
```
## Listar todos os relatórios de análise de performance da instância de banco de dados
O exemplo a seguir lista todos os relatórios de análise de performance disponíveis para o banco de dados `db-loadtest-0`.
```
aws pi list-performance-analysis-reports \
--service-type RDS \
--identifier db-loadtest-0 \
--region us-west-2
```
A resposta lista todos os relatórios com o ID do relatório, o status e os detalhes do período.
```
{
"AnalysisReports": [
{
"Status": "Succeeded",
"EndTime": 1680587086.584,
"CreationTime": 1680587087.139,
"StartTime": 1680583486.584,
"AnalysisReportId": "report-0d99cc91c4422ee61"
},
{
"Status": "Succeeded",
"EndTime": 1681491137.914,
"CreationTime": 1681491145.973,
"StartTime": 1681487537.914,
"AnalysisReportId": "report-002633115cc002233"
},
{
"Status": "Succeeded",
"EndTime": 1681493499.849,
"CreationTime": 1681493507.762,
"StartTime": 1681489899.849,
"AnalysisReportId": "report-043b1e006b47246f9"
},
{
"Status": "InProgress",
"EndTime": 1682979503.0,
"CreationTime": 1682979618.994,
"StartTime": 1682969503.0,
"AnalysisReportId": "report-01ad15f9b88bcbd56"
}
]
}
```
## Excluir um relatório de análise de performance
O exemplo a seguir exclui o relatório de análise do banco de dados `db-loadtest-0`.
```
aws pi delete-performance-analysis-report \
--service-type RDS \
--identifier db-loadtest-0 \
--analysis-report-id report-0d99cc91c4422ee61 \
--region us-west-2
```
## Adicionar tags a um relatório de análise de performance
O exemplo a seguir adiciona uma tag com uma chave `name` e um valor `test-tag` ao relatório `report-01ad15f9b88bcbd56`.
```
aws pi tag-resource \
--service-type RDS \
--resource-arn arn:aws:pi:us-west-2:356798100956:perf-reports/RDS/db-loadtest-0/report-01ad15f9b88bcbd56 \
--tags Key=name,Value=test-tag \
--region us-west-2
```
## Listar todas as tags para um relatório de análise de performance
O exemplo a seguir lista todas as tags do relatório `report-01ad15f9b88bcbd56`.
```
aws pi list-tags-for-resource \
--service-type RDS \
--resource-arn arn:aws:pi:us-west-2:356798100956:perf-reports/RDS/db-loadtest-0/report-01ad15f9b88bcbd56 \
--region us-west-2
```
A resposta lista o valor e a chave de todas as tags adicionadas ao relatório:
```
{
"Tags": [
{
"Value": "test-tag",
"Key": "name"
}
]
}
```
## Excluir tags de um relatório de análise de performance
O exemplo a seguir exclui a tag `name` do relatório `report-01ad15f9b88bcbd56`.
```
aws pi untag-resource \
--service-type RDS \
--resource-arn arn:aws:pi:us-west-2:356798100956:perf-reports/RDS/db-loadtest-0/report-01ad15f9b88bcbd56 \
--tag-keys name \
--region us-west-2
```
Depois que a tag for excluída, chamar a API `list-tags-for-resource` não listará essa tag.