Criar relatórios interativos com Azure Monitor pastas de trabalhoCreate interactive reports with Azure Monitor workbooks

As pastas de trabalho combinam texto, consultas de análise, métricas do Azure e parâmetros em relatórios interativos sofisticados.Workbooks combine text, Analytics queries, Azure Metrics, and parameters into rich interactive reports. As pastas de trabalho são editáveis por outros membros da equipe que têm acesso aos mesmos recursos do Azure.Workbooks are editable by any other team members who have access to the same Azure resources.

As pastas de trabalho são úteis para cenários como:Workbooks are helpful for scenarios like:

  • Explorando o uso de seu aplicativo quando você não conhece as métricas de interesse com antecedência: números de usuários, taxas de retenção, taxas de conversão, etc. Ao contrário de outras ferramentas de análise de uso, as pastas de trabalho permitem combinar vários tipos de visualizações e análises, tornando-as excelentes para esse tipo de exploração de forma livre.Exploring the usage of your app when you don't know the metrics of interest in advance: numbers of users, retention rates, conversion rates, etc. Unlike other usage analytics tools, workbooks let you combine multiple kinds of visualizations and analyses, making them great for this kind of free-form exploration.
  • Explicando à sua equipe como um recurso recém-lançado está sendo executado, mostrando as contagens de usuários para as principais interações e outras métricas.Explaining to your team how a newly released feature is performing, by showing user counts for key interactions and other metrics.
  • Compartilhando os resultados de um experimento A/B em seu aplicativo com outros membros de sua equipe.Sharing the results of an A/B experiment in your app with other members of your team. Você pode explicar as metas para o experimento com texto e, em seguida, mostrar cada métrica de uso e consulta de análise usada para avaliar o experimento, juntamente com as chamadas claras para se cada métrica estava acima ou abaixo do destino.You can explain the goals for the experiment with text, then show each usage metric and Analytics query used to evaluate the experiment, along with clear call-outs for whether each metric was above- or below-target.
  • Relatar o impacto de uma interrupção no uso de seu aplicativo, combinar dados, explicação de texto e uma discussão das próximas etapas para evitar interrupções no futuro.Reporting the impact of an outage on the usage of your app, combining data, text explanation, and a discussion of next steps to prevent outages in the future.

Iniciando com um modelo ou pasta de trabalho salvaStarting with a template or saved workbook

Uma pasta de trabalho é composta por seções que consistem em gráficos, tabelas, texto e controles de entrada independentemente de serem editados.A workbook is made up of sections consisting of independently editable charts, tables, text, and input controls. Para entender melhor as pastas de trabalho, é melhor abrir uma.To better understand workbooks, it is best to open one up.

Selecione pastas de trabalho no menu à esquerda de dentro da experiência de Application insights para seu aplicativo.Select Workbooks from the left-hand menu from inside the Application Insights experience for your app.

Captura de tela de navegação para pastas de trabalho

Isso inicia uma galeria de pastas de trabalho com várias pastas de trabalho predefinidas para ajudá-lo a começar.This launches a workbook gallery with a number of prebuilt workbooks to help you get started.

Captura de tela da Galeria de pastas de trabalho

Começaremos com o modelo padrão, localizado no início rápidodo título.We'll start with the Default Template, which is located under the heading Quick start.

Captura de tela da Galeria de pastas de trabalho

Editando, reorganizando, clonando e excluindo seções da pasta de trabalhoEditing, rearranging, cloning, and deleting workbook sections

As pastas de trabalho têm dois modos: modo de ediçãoe modo de leitura.Workbooks have two modes: editing mode, and reading mode. Quando a pasta de trabalho padrão é iniciada pela primeira vez, ela é aberta no modo de edição.When the default workbook is first launched, it opens in editing mode. Isso mostra todo o conteúdo da pasta de trabalho, incluindo quaisquer etapas e parâmetros ocultos.This shows all the content of the workbook, including any steps and parameters that are otherwise hidden. O modo de leitura apresenta uma exibição de estilo de relatório simplificada.Reading mode presents a simplified report style view. Isso permite abstrair a complexidade da criação de um relatório e ainda ter a mecânica subjacente apenas alguns cliques quando necessário para modificação.This allows you to abstract away the complexity that went into creating a report while still having the underlying mechanics only a few clicks away when needed for modification.

Controles de edição da seção Application Insights pastas de trabalho

  1. Quando terminar de editar uma seção, clique em edição concluída no canto inferior esquerdo da seção.When you're done editing a section, click Done Editing in the bottom left corner of the section.

  2. Para criar uma duplicata de uma seção, clique no ícone clonar esta seção .To create a duplicate of a section, click the Clone this section icon. A criação de seções duplicadas é uma ótima maneira de iterar em uma consulta sem perder as iterações anteriores.Creating duplicate sections is a great to way to iterate on a query without losing previous iterations.

  3. Para mover uma seção para cima em uma pasta de trabalho, clique no ícone mover para cima ou mover para baixo .To move up a section in a workbook, click the Move up or Move down icon.

  4. Para remover uma seção permanentemente, clique no ícone remover .To remove a section permanently, click the Remove icon.

Adicionando seções de texto e reduçãoAdding text and Markdown sections

Adicionar títulos, explicações e comentários às suas pastas de trabalho ajuda a transformar um conjunto de tabelas e gráficos em uma narração.Adding headings, explanations, and commentary to your workbooks helps turn a set of tables and charts into a narrative. As seções de texto em pastas de trabalho dão suporte à sintaxe de redução para formatação de texto, como títulos, negrito, itálico e listas com marcadores.Text sections in workbooks support the Markdown syntax for text formatting, like headings, bold, italics, and bulleted lists.

Para adicionar uma seção de texto à pasta de trabalho, use o botão Adicionar texto na parte inferior da pasta de trabalho ou na parte inferior de qualquer seção.To add a text section to your workbook, use the Add text button at the bottom of the workbook, or at the bottom of any section.

Adicionando seções de consultaAdding query sections

Seção de consulta em pastas de trabalho

Para adicionar a seção de consulta à sua pasta de trabalho, use o botão Adicionar consulta na parte inferior da pasta de trabalho ou na parte inferior de qualquer seção.To add query section to your workbook, use the Add query button at the bottom of the workbook, or at the bottom of any section.

As seções de consulta são altamente flexíveis e podem ser usadas para responder a perguntas como:Query sections are highly flexible and can be used to answer questions like:

  • Quantas exceções o site emitiu durante o mesmo período de tempo como um declínio no uso?How many exceptions did your site throw during the same time period as a decline in usage?
  • Qual foi a distribuição de tempos de carregamento de página para usuários que visualizam alguma página?What was the distribution of page load times for users viewing some page?
  • Quantos usuários exibiram algum conjunto de páginas no seu site, mas não algum outro conjunto de páginas?How many users viewed some set of pages on your site, but not some other set of pages? Isso pode ser útil para entender se você tem clusters de usuários que usam subconjuntos diferentes da funcionalidade do site (use o operador de join com o modificador kind=leftanti na linguagem de consulta Kusto).This can be useful to understand if you have clusters of users who use different subsets of your site's functionality (use the join operator with the kind=leftanti modifier in the Kusto query language).

Você também não está limitado a consultar o contexto do aplicativo do qual iniciou a pasta de trabalho.You also aren't only limited to querying from the context of the application you launched the workbook from. Você pode consultar vários Application Insights aplicativos monitorados, bem como espaços de trabalho de Log Analytics, contanto que tenha permissão de acesso a esses recursos.You can query across multiple Application Insights monitored apps as well as Log Analytics workspaces as long as you have access permission to those resources.

Para consultar recursos de Application Insights externos adicionais, use o identificador do aplicativo .To query from additional external Application Insights resources use the app identifier.

union app('app01').requests, app('app02').requests, requests
| summarize count() by bin(timestamp, 1h)

Essa consulta combina solicitações de três aplicativos diferentes.This query is combining requests from three different applications. Um aplicativo chamado app01, um aplicativo chamado app02 e as solicitações do recurso de Application Insights local.An app named app01, an app named app02, and the requests from the local Application Insights resource.

Para efetuar pull de dados de um espaço de trabalho de Log Analytics externo, use o identificador de espaço de trabalho .To pull in data from an external Log Analytics workspace use the workspace identifier.

Para saber mais sobre consultas entre recursos, consulte a orientação oficial.To learn more about cross-resource queries refer to the official guidance.

Configurações avançadas de consulta analíticaAdvanced analytic query settings

Cada seção tem suas próprias configurações avançadas, que podem ser acessadas por meio do ícone de configurações seção Application Insights pastas de trabalho editar controles localizados à direita do botão adicionar parâmetros .Each section has its own advanced settings, which are accessible via the settings icon Application Insights Workbooks section editing controls located to the right of the Add parameters button.

Controles de edição da seção Application Insights pastas de trabalho

Largura personalizadaCustom width Defina isso para tornar um item um tamanho arbitrário, para que você possa ajustar muitos itens em uma única linha, permitindo que você organize melhor seus gráficos e tabelas em relatórios interativos sofisticados.Set this to make an item an arbitrary size, so you can fit many items on a single line allowing you to better organize your charts and tables into rich interactive reports.
Condicionalmente visívelConditionally visible Use isso para ocultar as etapas com base em um parâmetro no modo de leitura.Use this to hide steps based on a parameter when in reading mode.
Exportar um parâmetroExport a parameter Isso permite que uma linha selecionada na grade ou no gráfico cause etapas posteriores para alterar valores ou tornar-se visível.This allows a selected row in the grid or chart to cause later steps to change values or become visible.
Mostrar consulta quando não estiver editandoShow query when not editing Isso exibe a consulta acima do gráfico ou tabela, mesmo quando estiver no modo de leitura.This displays the query above the chart or table even when in reading mode.
Mostrar botão abrir no Analytics quando não estiver editandoShow open in analytics button when not editing Isso adiciona o ícone de análise azul ao canto direito do gráfico para permitir o acesso com um clique.This adds the blue Analytics icon to the right-hand corner of the chart to allow one-click access.

A maioria dessas configurações é bastante intuitiva, mas para entender a exportação de um parâmetro , é melhor examinar uma pasta de trabalho que usa essa funcionalidade.Most of these settings are fairly intuitive, but to understand Export a parameter it is better to examine a workbook that makes use of this functionality.

Uma das pastas de trabalho predefinidas fornece informações sobre usuários ativos.One of the prebuilt workbooks provides information on Active Users.

A primeira seção da pasta de trabalho baseia-se nos dados de consulta analítica:The first section of the workbook is based on Analytic query data:

Controles de edição da seção Application Insights pastas de trabalho

A segunda seção também é baseada em dados de consulta analítica, mas a seleção de uma linha na primeira tabela atualizará interativamente o conteúdo do gráfico:The second section is also based on analytic query data, but selecting a row in the first table will interactively update the contents of the chart:

Controles de edição da seção Application Insights pastas de trabalho

Isso é possível por meio do uso de quando um item é selecionado, exportar configurações avançadas de parâmetro que estão habilitadas na consulta de análise da tabela.This is possible through use of the When an item is selected, export a parameter advanced settings that are enabled in the table's Analytics query.

Controles de edição da seção Application Insights pastas de trabalho

Em seguida, a segunda consulta de análise utiliza os valores exportados quando uma linha é selecionada.The second analytics query then utilizes the exported values when a row is selected. Se nenhuma linha for selecionada, o padrão será a linha que representa os valores gerais.If no row is selected, it defaults to the row representing the overall values.

let start = startofday(ago({TimeRange} + {Metric}));
union customEvents, pageViews
| where timestamp >= start
| where name in ({Activities}) or '*' in ({Activities}) or ('%' in ({Activities}) and itemType == 'pageView') or ('#' in ({Activities}) and itemType == 'customEvent')
{OtherFilters}
| where '{Filter}' == '' or '{Filter}' == '🔸 Overall' or {AnalyzeBy} == replace('🔹 ', '', '{Filter}')
| evaluate activity_engagement(user_Id, timestamp, start, now(), 1d, {Metric})
| where timestamp >= startofday(ago({TimeRange}))
| project timestamp, ["Active User"] = dcount_activities_outer
| render timechart 

Adicionando seções de métricasAdding metrics sections

As seções de métricas oferecem acesso completo para incorporar Azure Monitor dados de métricas em seus relatórios interativos.Metrics sections give you full access to incorporate Azure Monitor metrics data into your interactive reports. Muitas das pastas de trabalho predefinidas conterão dados de consulta analítica e dados de métrica, permitindo que você aproveite ao máximo os dois recursos em um só lugar.Many of the prebuilt workbooks will contain both analytic query data and metric data allowing you to take full advantage of the best of both features all in one place. Você também tem a capacidade de extrair dados de métrica de recursos em qualquer uma das assinaturas às quais você tem acesso.You also have the ability to pull in metric data from resources in any of the subscriptions you have access to.

Aqui está um exemplo de dados da máquina virtual que estão sendo obtidos em uma pasta de trabalho para fornecer uma visualização em grade do desempenho da CPU:Here is an example of Virtual machine data being pulled into a workbook to provide a grid visualization of CPU performance:

Controles de edição da seção Application Insights pastas de trabalho

Adicionando seções de parâmetroAdding parameter sections

Os parâmetros da pasta de trabalho permitem alterar valores na pasta de trabalho sem precisar editar manualmente as seções de consulta ou texto.Workbook parameters allow you to change values in the workbook without having to manually edit the query or text sections. Isso elimina a necessidade de entender a linguagem de consulta de análise subjacente e expandir muito o possível público de relatórios baseados em pastas de trabalho.This removes the requirement of needing to understand the underlying analytics query language and greatly expands the potential audience of workbook-based reporting.

Os valores dos parâmetros são substituídos em seções de consulta, texto ou outro parâmetro, colocando o nome do parâmetro entre chaves, como {parameterName}.The values of parameters are replaced in query, text or other parameter sections by putting the name of the parameter in braces, like {parameterName}. Os nomes de parâmetro são limitados a regras semelhantes como identificadores JavaScript, basicamente caracteres alfabéticos ou sublinhados, seguidos de caracteres alfanuméricos ou sublinhados.Parameter names are limited to similar rules as JavaScript identifiers, basically alphabetic characters or underscores, followed by alphanumeric characters or underscores. Por exemplo, a1 é permitido, mas 1a não é permitido.For example, a1 is allowed, but 1a is not allowed.

Os parâmetros são lineares, começando na parte superior de uma pasta de trabalho e fluindo para etapas posteriores.Parameters are linear, starting from the top of a workbook and flowing down to later steps. Os parâmetros declarados posteriormente em uma pasta de trabalho podem substituir aqueles que foram declarados mais detalhadamente.Parameters declared later in a workbook can override those that were declared further up. Isso também permite que os parâmetros que usam consultas acessem os valores dos parâmetros definidos mais adiante.This also lets parameters that use queries to access the values from parameters defined further up. Dentro da própria etapa de um parâmetro, os parâmetros também são lineares, da esquerda para a direita, em que os parâmetros à direita podem depender de um parâmetro declarado anteriormente na mesma etapa.Within a parameter's step itself, parameters are also linear, left to right, where parameters to the right can depend on a parameter declared earlier in that same step.

Há quatro tipos diferentes de parâmetros com suporte no momento:There are four different types of parameters which are currently supported:

Text (Texto)Text o usuário Editará uma caixa de texto e, opcionalmente, você poderá fornecer uma consulta para preencher o valor padrão.the user will edit a text box, and you can optionally supply a query to fill in the default value.
Lista suspensaDrop down O usuário escolherá um conjunto de valores.The user will choose from a set of values.
Seletor de intervalo de tempoTime range picker O usuário escolherá um conjunto predefinido de valores de intervalo de tempo ou escolherá um intervalo de tempo personalizado.The user will choose from a predefined set of time range values, or pick from a custom time range.
Seletor de recursosResource picker O usuário escolherá os recursos selecionados para a pasta de trabalho.The user will choose from the resources selected for the workbook.

Usando um parâmetro de textoUsing a text parameter

O valor que um usuário digita na caixa de texto é substituído diretamente na consulta, sem escape ou quot.The value a user types in the textbox is replaced directly in the query, with no escaping or quoting. Se o valor necessário for uma cadeia de caracteres, a consulta deverá ter aspas em volta do parâmetro (como ' {Parameter} ' ).If the value you need is a string, the query should have quotes around the parameter (like '{parameter}').

Isso permite que o valor em uma caixa de texto seja usado em qualquer lugar.This allows the value in a text box to be used anywhere. Pode ser um nome de tabela, nome de coluna, nome de função, operador, etc.It can be a table name, column name, function name, operator, etc.

O tipo de parâmetro de texto tem uma configuração obter valor padrão da consulta de análise, que permite que o autor da pasta de trabalho use uma consulta para popular o valor padrão dessa caixa de texto.The text parameter type has a setting Get default value from analytics query, which allows the workbook author to use a query to populate the default value for that textbox.

Ao usar o valor padrão de uma consulta de análise, somente o primeiro valor da primeira linha (linha 0, coluna 0) é usado como o valor padrão.When using the default value from an analytics query, only the first value of the first row (row 0, column 0) is used as the default value. Portanto, é recomendável limitar sua consulta para retornar apenas uma linha e uma coluna.Therefore it is recommended to limit your query to return just one row and one column. Todos os outros dados retornados pela consulta são ignorados.Any other data returned by the query is ignored.

Qualquer valor que a consulta retornar será substituído diretamente sem escape ou quot.Whatever value the query returns will be replaced directly with no escaping or quoting. Se a consulta não retornar nenhuma linha, o resultado do parâmetro será uma cadeia de caracteres vazia (se o parâmetro não for necessário) ou indefinido (se o parâmetro for necessário).If the query returns no rows, the result of the parameter is either an empty string (if the parameter is not required) or undefined (if the parameter is required).

Usando uma lista suspensaUsing a dropdown

O tipo de parâmetro DropDown permite criar um controle suspenso, permitindo a seleção de um ou vários valores.The dropdown parameter type lets you create a dropdown control, allowing the selection of one or many values.

A lista suspensa é preenchida por uma consulta de análise.The dropdown is populated by an analytics query. Se a consulta retornar uma coluna, os valores nessa coluna serão o valor e o rótulo no controle suspenso.If the query returns one column, the values in that column are both the value and the label in the dropdown control. Se a consulta retornar duas colunas, a primeira coluna será o valore a segunda coluna será o rótulo mostrado na lista suspensa.If the query returns two columns, the first column is the value, and the second column is the label shown in the dropdown. Se a consulta retornar três colunas, a 3ª coluna será usada para indicar a seleção padrão nesse menu suspenso.If the query returns three columns, the 3rd column is used to indicate the default selection in that dropdown. Essa coluna pode ser qualquer tipo, mas a mais simples é usar tipos bool ou numéricos, em que 0 é false e 1 é verdadeiro.This column can be any type, but the simplest is to use bool or numeric types, where 0 is false, and 1 is true.

Se a coluna for um tipo de cadeia de caracteres, uma cadeia de caracteres nula/vazia será considerada falsa e qualquer outro valor será considerado verdadeiro.If the column is a string type, null/empty string is considered false, and any other value is considered true. Para listas suspensas de seleção única, o primeiro valor com um valor true é usado como a seleção padrão.For single selection dropdowns, the first value with a true value is used as the default selection. Para listas suspensas de seleção múltipla, todos os valores com um valor true são usados como o conjunto selecionado padrão.For multiple selection dropdowns, all values with a true value are used as the default selected set. Os itens na lista suspensa são mostrados em qualquer ordem em que a consulta retorna linhas.The items in the dropdown are shown in whatever order the query returned rows.

Vamos examinar os parâmetros presentes no relatório de usuários ativos.Let's look at the parameters present in the Active Users report. Clique no símbolo de edição ao lado de timerange.Click the edit symbol next to TimeRange.

Controles de edição da seção Application Insights pastas de trabalho

Isso abrirá o item de menu Editar parâmetro:This will launch the Edit Parameter menu item:

Controles de edição da seção Application Insights pastas de trabalho

A consulta usa um recurso da linguagem de consulta do Analytics chamado DataTable que permite gerar uma tabela arbitrária, cheia de conteúdo, sem ar fino!The query uses a feature of the analytics query language called a datatable that lets you generate an arbitrary table, full of content, out of thin air! Por exemplo, a seguinte consulta de análise:For example, the following analytics query:

datatable( column1:string, column2:string )
[
 "row 1 column 1", "row 1 column 2",
"row 2 column 1", "row 2 column 2"
]

Gera o resultado:Generates the result:

Controles de edição da seção Application Insights pastas de trabalho

Um exemplo mais aplicável é usar uma lista suspensa para escolher um conjunto de países/regiões por nome:A more applicable example is using a dropdown to pick from a set of countries/regions by name:

customEvents
| where timestamp >= ago(14d)
| summarize count() by client_CountryOrRegion
| top 100 by count_
| project  client_CountryOrRegion 
| order by client_CountryOrRegion asc

A consulta exibirá os resultados da seguinte maneira:The query will display results as follows:

Lista suspensa de país

As listas suspensas são ferramentas incrivelmente poderosas para personalizar e criar relatórios interativos.Dropdowns are incredibly powerful tools for customizing and creating interactive reports.

Parâmetros de intervalo de tempoTime range parameters

Embora seja possível criar seu próprio parâmetro de intervalo de tempo personalizado por meio do tipo de parâmetro DropDown, você também pode usar o tipo de parâmetro de intervalo de tempo pronto para uso se não precisar do mesmo grau de flexibilidade.While you can make your own custom time range parameter via the dropdown parameter type, you can also use the out-of-box time range parameter type if you don't need the same degree of flexibility.

Os tipos de parâmetro de intervalo de tempo têm 15 intervalos padrão que vão de cinco minutos até os últimos 90 dias.Time range parameter types have 15 default ranges that go from five minutes to the last 90 days. Há também uma opção para permitir a seleção de intervalo de tempo personalizado, que permite que o operador do relatório escolha valores explícitos de início e parada para o intervalo de tempo.There is also an option to allow custom time range selection, which allows the operator of the report to choose explicit start and stop values for the time range.

Seletor de recursosResource picker

O tipo de parâmetro do seletor de recursos oferece a capacidade de fazer o escopo do relatório para determinados tipos de recursos.The resource picker parameter type gives you the ability to scope your report to certain types of resources. Um exemplo de pasta de trabalho predefinida que utiliza o tipo de seletor de recursos é a pasta de trabalho de informações de falha .An example of prebuilt workbook that leverages the resource picker type is the Failure Insights workbook.

Lista suspensa de país

Salvando e compartilhando pastas de trabalho com sua equipeSaving and sharing workbooks with your team

As pastas de trabalho são salvas em um recurso de Application Insights, na seção meus relatórios , que é particular para você ou na seção relatórios compartilhados , que é acessível a todos com acesso ao recurso de Application insights.Workbooks are saved within an Application Insights resource, either in the My Reports section that's private to you or in the Shared Reports section that's accessible to everyone with access to the Application Insights resource. Para exibir todas as pastas de trabalho no recurso, clique no botão abrir na barra de ação.To view all the workbooks in the resource, click the Open button in the action bar.

Para compartilhar uma pasta de trabalho que está atualmente em meus relatórios:To share a workbook that's currently in My Reports:

  1. Clique em abrir na barra de açãoClick Open in the action bar
  2. Clique no botão "..." botão ao lado da pasta de trabalho que você deseja compartilharClick the "..." button beside the workbook you want to share
  3. Clique em mover para relatórios compartilhados.Click Move to Shared Reports.

Para compartilhar uma pasta de trabalho com um link ou por email, clique em compartilhar na barra de ação.To share a workbook with a link or via email, click Share in the action bar. Tenha em mente que os destinatários do link precisam de acesso a esse recurso no portal do Azure para exibir a pasta de trabalho.Keep in mind that recipients of the link need access to this resource in the Azure portal to view the workbook. Para fazer edições, os destinatários precisam de pelo menos permissões de colaborador para o recurso.To make edits, recipients need at least Contributor permissions for the resource.

Para fixar um link em uma pasta de trabalho em um painel do Azure:To pin a link to a workbook to an Azure Dashboard:

  1. Clique em abrir na barra de açãoClick Open in the action bar
  2. Clique no botão "..." botão ao lado da pasta de trabalho que você deseja fixarClick the "..." button beside the workbook you want to pin
  3. Clique em fixar no painel.Click Pin to dashboard.

Modelos de pasta de trabalho de contribuiçãoContributing workbook templates

Você criou um modelo de pasta de trabalho incrível e deseja compartilhá-lo com a Comunidade?Have you created an awesome workbook template and want to share it with the community? Para saber mais, visite nosso repositório GitHub.To learn more, visit our GitHub repo.

Passos seguintesNext steps