As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Conectar-se a uma fonte de dados do Microsoft SQL Server Use a fonte de dados Microsoft SQL Server (MSSQL) para consultar e visualizar dados de qualquer Microsoft SQL Server 2005 ou mais recente, incluindo o banco de dados SQL do Microsoft Azure. **Importante** O Grafana versão 8.0 altera a estrutura de dados subjacente dos quadros de dados do Microsoft SQL Server, Postgres e MySQL. Como consequência, o resultado de uma consulta de série temporal é retornado em um formato amplo. Para obter mais informações, consulte [Wide format](https://grafana.com/developers/plugin-tools/introduction/data-frames#wide-format) na documentação dos quadros de dados do Grafana. Para que as visualizações funcionem como antes, talvez seja necessário fazer algumas migrações manuais. Uma solução está documentada no Github em [Postgres/MySQL/MSSQL: Alteração significativa na v8.0 relacionada a consultas de séries temporais e ordenação](https://github.com/grafana/grafana/issues/35534) da coluna de dados. ## Adicionar a fonte de dados 1. Abra o menu lateral escolhendo o ícone do Grafana no cabeçalho superior. 1. No menu lateral, sob o link **Configuração**, você encontrará um link **Fontes de dados**. 1. Escolha o botão **\$1 Adicionar fonte de dados** no cabeçalho superior. 1. Selecione **Microsoft SQL Server** na lista suspensa **Tipo**. ### Opções de fontes de dados. | Name (Nome) | Description | | --- | --- | | Name | O nome da fonte de dados. É assim que você vê a fonte de dados nos painéis e consultas. | | Default | Fonte de dados padrão significa que ela será pré-selecionada para novos painéis. | | Host | O IP address/hostname e a porta opcional da sua instância MSSQL. Se a porta for omitida, o padrão 1433 será usado. | | Database | Nome do banco de dados MSSQL. | | User | Login e nome de usuário do banco de dados. | | Password | Senha do usuário do banco de dados. | | Encrypt | Essa opção determina se ou em que medida uma TCP/IP conexão SSL segura será negociada com o servidor, padrão (falseGrafana v5.4\$1). | | Max open | O número máximo de conexões abertas com o banco de dados, padrão unlimited (Grafana v5.4\$1). | | Max idle | O número máximo de conexões no pool de conexões ociosas, padrão 2 (Grafana v5.4\$1). | | Max lifetime | O tempo máximo, em segundos, em que uma conexão pode ser reutilizada. O padrão é 14400/4 horas. | ### Intervalo de tempo mínimo Um limite mínimo para as variáveis `$_interval` e `$_interval_ms`. É recomendável definir a frequência de gravação, por exemplo, `1m` se os dados forem gravados a cada minuto. Essa opção também pode estar overridden/configured em um painel de controle em opções de fonte de dados. Esse valor **deve** ser formatado como um número seguido por um identificador de tempo válido, por exemplo, `1m` (1 minuto) ou `30s` (30 segundos). As fontes de identidade a seguir são compatíveis. | Identificador | Description | | --- | --- | | y | Ano | | M | Mês | | w | Semana | | d | Dia | | h | Hora | | m | Minuto | | s | Segunda | | ms | Milissegundo | ### Permissões de usuário do banco de dados **Importante** O usuário do banco de dados que você especifica ao adicionar a fonte de dados só deve receber permissões SELECT no banco de dados e nas tabelas específicos que você deseja consultar. O Grafana não valida se a consulta é segura. A consulta pode incluir qualquer instrução SQL. Por exemplo, instruções como `DELETE FROM user;` e `DROP TABLE user;` seriam executadas. Para se proteger contra isso, é altamente recomendável que você crie um usuário específico do MSSQL com permissões restritas. O código de exemplo a seguir mostra a criação de um usuário específico do MSSQL com permissões restritas. ``` CREATE USER grafanareader WITH PASSWORD 'password' GRANT SELECT ON dbo.YourTable3 TO grafanareader ``` Certifique-se de que o usuário não receba nenhuma permissão indesejada do perfil público. ### Problemas conhecidos Se você estiver usando uma versão mais antiga do Microsoft SQL Server, como 2008 e 2008R2, talvez seja necessário desabilitar a criptografia para poder se conectar. Se possível, recomendamos que você use o pacote de serviços mais recente disponível para otimizar a compatibilidade. ## Editor de consultas Você encontrará o editor de consultas MSSQL na guia de métricas no modo de edição do grafo, Singlestat ou painel de tabela. Você entra no modo de edição escolhendo o título do painel e, depois, Editar. O editor permite que você defina uma consulta SQL para selecionar dados a serem visualizados. 1. Selecione *Formatar como* `Time series` (para uso no painel de Grafo ou Singlestat , entre outros) ou `Table` (para uso no painel de Tabela, entre outros). 1. Este é o editor real em que você escreve as consultas SQL. 1. Mostre a seção de ajuda do MSSQL abaixo do editor de consultas. 1. Mostre a consulta SQL que foi executada. Estará disponível primeiro após a execução com êxito de uma consulta. 1. Adicione uma consulta adicional em que um editor de consultas adicional será exibido. ## Macros Para simplificar a sintaxe e permitir partes dinâmicas, como filtros de intervalo de datas, a consulta pode conter macros. | Exemplo de macro | Description | | --- | --- | | \$1\$1\$1time(dateColumn) | Será substituído por uma expressão para renomear a coluna para hora. Por exemplo, dateColumn as time . | | \$1\$1\$1timeEpoch(dateColumn) | Será substituído por uma expressão para converter um tipo de coluna DATETIME em carimbo de data e hora do Unix e renomeá-lo para hora. Por exemplo, DATEDIFF(second, "1970-01-01", dateColumn) AS time. | | \$1\$1\$1timeFilter(dateColumn) | Será substituído por um filtro de intervalo de tempo usando o nome da coluna especificada. Por exemplo, dateColumn BETWEEN "2017-04-21T05:01:17Z" AND "2017-04-21T05:06:17Z". | | \$1\$1\$1timeFrom() | Será substituído pelo início da seleção de hora atualmente ativa. Por exemplo, "2017-04-21T05:01:17Z". | | \$1\$1\$1timeTo() | Será substituído pelo final da seleção de hora atualmente ativa. Por exemplo, "2017-04-21T05:06:17Z". | | \$1\$1\$1timeGroup(dateColumn,'5m'[, fillvalue]) | Será substituído por uma expressão utilizável na cláusula GROUP BY. Fornecer um fillValue de valor NULL ou flutuante preencherá automaticamente as séries vazias no intervalo de tempo com esse valor. Por exemplo, CAST(ROUND(DATEDIFF(second, "1970-01-01", time\$1column)/300.0, 0) as bigint)\$1300. | | \$1\$1\$1timeGroup(dateColumn,'5m', 0) | O mesmo que o anterior, mas com um parâmetro de preenchimento, assim os pontos ausentes nessa série serão adicionados pelo Grafana e 0 será usado como valor. | | \$1\$1\$1timeGroup(dateColumn,'5m', NULL) | O mesmo que acima, mas NULL será usado como valor para pontos ausentes. | | \$1\$1\$1timeGroup(dateColumn,'5m', previous) | O mesmo que acima, mas o valor anterior dessa série será usado como valor de preenchimento se nenhum valor tiver sido visto ainda. NULL será usado (disponível apenas no Grafana 5.3\$1). | O editor de consultas tem um link **SQL gerado** que aparece após a execução de uma consulta, no modo de edição do painel. Escolha-o e ele se expandirá e mostrará a string SQL bruta interpolada que foi executada. ## Consultas de tabelas Se a opção de consulta estiver definida como **Formatar como****Tabela**, você poderá basicamente fazer qualquer tipo de consulta SQL. O painel da tabela mostrará automaticamente os resultados das colunas e linhas retornadas pela consulta. O exemplo de código a seguir mostra uma tabela do banco de dados. ``` CREATE TABLE [event] ( time_sec bigint, description nvarchar(100), tags nvarchar(100), ) ``` ``` CREATE TABLE [mssql_types] ( c_bit bit, c_tinyint tinyint, c_smallint smallint, c_int int, c_bigint bigint, c_money money, c_smallmoney smallmoney, c_numeric numeric(10,5), c_real real, c_decimal decimal(10,2), c_float float, c_char char(10), c_varchar varchar(10), c_text text, c_nchar nchar(12), c_nvarchar nvarchar(12), c_ntext ntext, c_datetime datetime, c_datetime2 datetime2, c_smalldatetime smalldatetime, c_date date, c_time time, c_datetimeoffset datetimeoffset ) INSERT INTO [mssql_types] SELECT 1, 5, 20020, 980300, 1420070400, '$20000.15', '£2.15', 12345.12, 1.11, 2.22, 3.33, 'char10', 'varchar10', 'text', N'☺nchar12☺', N'☺nvarchar12☺', N'☺text☺', GETDATE(), CAST(GETDATE() AS DATETIME2), CAST(GETDATE() AS SMALLDATETIME), CAST(GETDATE() AS DATE), CAST(GETDATE() AS TIME), SWITCHOFFSET(CAST(GETDATE() AS DATETIMEOFFSET), '-07:00') ``` O exemplo de código a seguir mostra uma consulta. ``` SELECT * FROM [mssql_types] ``` Você pode controlar o nome das colunas do painel Tabela usando a sintaxe regular de seleção de coluna `AS` SQL, conforme mostrado no código de exemplo a seguir. ``` SELECT c_bit as [column1], c_tinyint as [column2] FROM [mssql_types] ``` O painel resultante da tabela: ## Consultas de séries temporais Se você definir **Formatar como** para **Série temporal**, para uso no painel de Grafo, por exemplo, a consulta deverá ter uma coluna chamada `time` que retorne uma data e hora SQL ou qualquer tipo de dados numéricos representando o Unix epoch em segundos. Você pode retornar uma coluna chamada `metric` que é usada como nome da métrica para a coluna de valor. Qualquer coluna, exceto `time` e `metric`, é tratada como uma coluna de valor. Se você omitir a coluna `metric`, o nome da coluna de valor será o nome da métrica. Você pode selecionar várias colunas de valor, e cada uma terá seu nome como métrica. Se você retornar várias colunas de valor e uma coluna chamada `metric`, então essa coluna será usada como prefixo para o nome da série. Os conjuntos de resultados das consultas de séries temporais devem ser classificados por hora. O exemplo de código a seguir mostra uma tabela do banco de dados. ``` CREATE TABLE [event] ( time_sec bigint, description nvarchar(100), tags nvarchar(100), ) ``` ``` CREATE TABLE metric_values ( time datetime, measurement nvarchar(100), valueOne int, valueTwo int, ) INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric A', 62, 6) INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric B', 49, 11) ... INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric A', 14, 25) INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric B', 48, 10) ``` O código de exemplo a seguir mostra um `value` e uma coluna de `metric`. ``` SELECT time, valueOne, measurement as metric FROM metric_values WHERE $__timeFilter(time) ORDER BY 1 ``` Quando a consulta anterior for usada em um painel de grafo, ela produzirá duas séries nomeadas `Metric A` e `Metric B` com os valores `valueOne` e `valueTwo` plotadas em `time`. O código de exemplo a seguir mostra várias colunas de `value`. ``` SELECT time, valueOne, valueTwo FROM metric_values WHERE $__timeFilter(time) ORDER BY 1 ``` Quando a consulta anterior for usada em um painel de grafo, ela produzirá duas séries nomeadas `Metric A` e `Metric B` com os valores `valueOne` e `valueTwo` plotadas em `time`. O código de exemplo a seguir mostra o uso do macro \$1\$1\$1timeGroup. ``` SELECT $__timeGroup(time, '3m') as time, measurement as metric, avg(valueOne) FROM metric_values WHERE $__timeFilter(time) GROUP BY $__timeGroup(time, '3m'), measurement ORDER BY 1 ``` Quando a consulta anterior for usada em um painel de grafo, ela produzirá duas séries nomeadas `Metric A` e `Metric B` com os valores `valueOne` e `valueTwo` plotadas em `time`. Quaisquer duas séries sem um valor em uma janela de três minutos renderizarão uma linha entre essas duas linhas. Você notará que o grafo à direita nunca desce até zero. O código de exemplo a seguir mostra o uso do macro \$1\$1\$1timeGroup com o parâmetro de preenchimento definido como zero. ``` SELECT $__timeGroup(time, '3m', 0) as time, measurement as metric, sum(valueTwo) FROM metric_values WHERE $__timeFilter(time) GROUP BY $__timeGroup(time, '3m'), measurement ORDER BY 1 ``` Quando essa consulta é usada em um painel de grafo, o resultado são duas séries denominadas `Metric A` e `Metric B` com uma soma de `valueTwo` plotadas em `time`. Qualquer série sem valor em uma janela de três minutos terá o valor de zero, que você verá renderizado no grafo à direita. ## Modelos Em vez da codificação rígida dos nomes de servidores, das aplicações e dos sensores em suas consultas de métricas, você pode usar variáveis no lugar deles. As variáveis são mostradas como caixas de seleção suspensas na parte superior do dashboard. Você pode usar essas caixas suspensas para alterar os dados exibidos no dashboard. Para obter mais informações sobre modelos e variáveis de modelos, consulte [Modelos e variáveis](templates-and-variables.md). ### Variável de consulta Caso adicione uma variável de modelo do tipo `Query`, você poderá escrever uma consulta MSSQL que possa retornar itens como nomes de medições, nomes de chave ou valores de chave que são mostrados como uma caixa de seleção suspensa. Por exemplo, você pode ter uma variável que contém todos os valores da coluna `hostname` em uma tabela caso especifique uma consulta como esta na configuração da variável de modelos da *Consulta*. ``` SELECT hostname FROM host ``` Uma consulta pode retornar várias colunas, e o Grafana criará automaticamente uma lista delas. Por exemplo, a consulta a seguir retornará uma lista com valores de `hostname` e `hostname2`. ``` SELECT [host].[hostname], [other_host].[hostname2] FROM host JOIN other_host ON [host].[city] = [other_host].[city] ``` Outra opção é uma consulta que pode criar uma key/value variável. A consulta deve retornar duas colunas denominadas `__text` e `__value`. O valor da coluna `__text` deve ser exclusivo (se não for exclusivo, o primeiro valor será usado). As opções na lista suspensa terão um texto e um valor que permitem que você tenha um nome amigável como texto e um ID como valor. Um exemplo de consulta com `hostname` como o texto e `id` como o valor: ``` SELECT hostname __text, id __value FROM host ``` Você também pode criar variáveis aninhadas. Por exemplo, se você tivesse outra variável denominada `region`. Então você pode fazer com que a variável hosts mostre apenas os hosts da região selecionada atualmente com uma consulta como esta (se `region` for uma variável de vários valores, use o operador `IN` de comparação em vez de `=` para comparar com vários valores). ``` SELECT hostname FROM host WHERE region IN ($region) ``` ### Usar variáveis em consultas **nota** Os valores das variáveis do modelo só ficam entre aspas quando a variável do modelo é de `multi-value`. Se a variável for uma variável de vários valores, então use o operador de comparação `IN` em vez de `=` para comparar com vários valores. Há duas sintaxes: `$` Exemplo com uma variável de modelo denominada `hostname`: ``` SELECT atimestamp time, aint value FROM table WHERE $__timeFilter(atimestamp) and hostname in($hostname) ORDER BY atimestamp ``` `[[varname]]` Exemplo com uma variável de modelo denominada `hostname`: ``` SELECT atimestamp as time, aint as value FROM table WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) ORDER BY atimestamp ``` #### Desativar a cotação para variáveis de vários valores O Grafana cria automaticamente uma string entre aspas e separada por vírgula para variáveis de vários valores. Por exemplo, se `server01` e `server02` forem selecionados, então será formatado como: `'server01', 'server02'`. Para desativar a citação, use a opção de formatação csv para variáveis. `${servers:csv}` Para obter mais informações sobre opções de formatação de variáveis, consulte [Modelos e variáveis](templates-and-variables.md). ## Anotações Você pode usar anotações para sobrepor informações importantes de eventos nos grafos. Você adiciona consultas de anotações por meio do menu Dashboard e da Visualização de anotações. Para obter mais informações, consulte [Anotações](dashboard-annotations.md). **Colunas:** | Name (Nome) | Description | | --- | --- | | time | O nome do date/time campo. Pode ser uma coluna com um tipo de date/time dados SQL nativo ou valor de época. | | timeend | Nome opcional do date/time campo final. Pode ser uma coluna com um tipo de date/time dados SQL nativo ou valor de época. | | text | Campo de descrição do evento. | | tags | Nome de campo opcional a ser usado para tags de eventos como uma string separada por vírgula. | O código de exemplo a seguir mostra tabelas de bancos de dados. ``` CREATE TABLE [events] ( time_sec bigint, description nvarchar(100), tags nvarchar(100), ) ``` Também usamos a tabela de banco de dados definida em [Consultas de séries temporais](#mssql-time-series-queries). O código de exemplo a seguir mostra uma consulta usando uma coluna de hora com valores epoch. ``` SELECT time_sec as time, description as [text], tags FROM [events] WHERE $__unixEpochFilter(time_sec) ORDER BY 1 ``` O código de exemplo a seguir mostra uma consulta de região usando colunas timeend com valores epoch. ``` SELECT time_sec as time, time_end_sec as timeend, description as [text], tags FROM [events] WHERE $__unixEpochFilter(time_sec) ORDER BY 1 ``` O código de exemplo a seguir mostra uma consulta usando uma coluna de tempo do tipo de date/time dados SQL nativo. ``` SELECT time, measurement as text, convert(varchar, valueOne) + ',' + convert(varchar, valueTwo) as tags FROM metric_values WHERE $__timeFilter(time_column) ORDER BY 1 ``` ## Compatível com procedimentos armazenados Os procedimentos armazenados foram verificados quanto ao funcionamento. No entanto, pode haver casos extremos em que não funcionará conforme o esperado. Os procedimentos armazenados devem ser compatíveis em consultas de tabela, série temporal e anotação, desde que você use a mesma nomenclatura de colunas e retorne dados no mesmo formato descrito anteriormente nas respectivas seções. As funções de macro não funcionarão dentro de um procedimento armazenado. ### Exemplos Para os exemplos a seguir, a tabela do banco de dados é definida nas consultas de séries temporais. Digamos que você queira visualizar quatro séries em um painel de grafo, como todas as combinações de colunas `valueOne`, `valueTwo` e `measurement`. O painel de grafo à direita mostra o que queremos alcançar. Para resolver essa questão, você deve usar duas consultas: O exemplo de código a seguir mostra a primeira consulta. ``` SELECT $__timeGroup(time, '5m') as time, measurement + ' - value one' as metric, avg(valueOne) as valueOne FROM metric_values WHERE $__timeFilter(time) GROUP BY $__timeGroup(time, '5m'), measurement ORDER BY 1 ``` O exemplo de código a seguir mostra a segunda consulta. ``` SELECT $__timeGroup(time, '5m') as time, measurement + ' - value two' as metric, avg(valueTwo) as valueTwo FROM metric_values GROUP BY $__timeGroup(time, '5m'), measurement ORDER BY 1 ``` #### Procedimento armazenado usando a hora no formato epoch Você pode definir um procedimento armazenado que retornará todos os dados necessários para renderizar quatro séries em um painel de grafo, como acima. Nesse caso, o procedimento armazenado aceita dois parâmetros, `@from` e `@to`, de tipos de dados `int`, que devem ser um intervalo de tempo (de-até) no formato epoch que será usado para filtrar os dados a serem retornados do procedimento armazenado. Isso imita `$__timeGroup(time, '5m')` nas expressões de seleção e agrupamento por, e é por isso que várias expressões longas são necessárias. Elas podem ser extraídas para funções do MSSQL, se desejado. ``` CREATE PROCEDURE sp_test_epoch( @from int, @to int ) AS BEGIN SELECT cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time, measurement + ' - value one' as metric, avg(valueOne) as value FROM metric_values WHERE time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01') GROUP BY cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int), measurement UNION ALL SELECT cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time, measurement + ' - value two' as metric, avg(valueTwo) as value FROM metric_values WHERE time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01') GROUP BY cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int), measurement ORDER BY 1 END ``` Depois, você pode usar a consulta a seguir para o painel de grafo. ``` DECLARE @from int = $__unixEpochFrom(), @to int = $__unixEpochTo() EXEC dbo.sp_test_epoch @from, @to ``` #### Procedimento armazenado usando hora no formato datetime Você pode definir um procedimento armazenado que retornará todos os dados necessários para renderizar quatro séries em um painel de grafo, como acima. Nesse caso, o procedimento armazenado aceita dois parâmetros, `@from` e `@to`, de tipos de dados `datetime`, que devem ser um intervalo de tempo (de-até) que será usado para filtrar os dados a serem retornados do procedimento armazenado. Isso imita `$__timeGroup(time, '5m')` nas expressões de seleção e agrupamento por, e é por isso que várias expressões longas são necessárias. Elas podem ser extraídas para funções do MSSQL, se desejado. ``` CREATE PROCEDURE sp_test_datetime( @from datetime, @to datetime ) AS BEGIN SELECT cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time, measurement + ' - value one' as metric, avg(valueOne) as value FROM metric_values WHERE time >= @from AND time <= @to GROUP BY cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int), measurement UNION ALL SELECT cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time, measurement + ' - value two' as metric, avg(valueTwo) as value FROM metric_values WHERE time >= @from AND time <= @to GROUP BY cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int), measurement ORDER BY 1 END ``` Depois, você pode usar a consulta a seguir para o painel de grafo. ``` DECLARE @from datetime = $__timeFrom(), @to datetime = $__timeTo() EXEC dbo.sp_test_datetime @from, @to ``` ## Geração de alertas As consultas de séries temporais devem funcionar em condições de alerta. As consultas formatadas em tabela ainda não são compatíveis em condições de regras de alerta.