> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-analytics.md).

# Ligar o Azure Log Analytics Workspace

Ligue um Azure Log Analytics workspace ao RealmJoin Portal com o módulo RealmJoin PowerShell para armazenar registos de auditoria, operacionais e de runbook no seu próprio tenant.

## Visão geral

O RealmJoin Portal pode usar um Log Analytics workspace na sua própria subscrição Azure para armazenar

* os seus **registo de auditoria** — cada ação executada no Portal, consulte [Registo de Auditoria](https://docs.realmjoin.com/pt/monitorizacao-e-registos/audit-log.md)
* os seus **registos operacionais**
* **registos de runbook**, arquivados para além da retenção máxima do Azure Automation (atualmente 30 dias)

O workspace é configurado com o [módulo PowerShell do RealmJoin](https://docs.realmjoin.com/pt/implementacao/onboarding-realmjoin-portal/advanced-setup.md). O Portal gera para si um comando pronto a copiar — não há nada a preencher manualmente.

{% hint style="info" %}
O Log Analytics já está configurado para o seu tenant e usa a API Data Collector descontinuada? Então siga [Migração para a API de Ingestão de Logs](https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-ingestion-api-migration.md) em vez disso — reutiliza o seu workspace existente e mantém os seus registos existentes.
{% endhint %}

## Componentes

O RealmJoin escreve os seus registos através do Azure Monitor **API Logs Ingestion**, com base em [Data Collection Rules (DCRs)](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-rule-overview) e autenticação Microsoft Entra ID. Executar o comando de configuração cria:

* O **Recursos Azure do RealmJoin** service principal no seu tenant Entra ID (se ainda não existir)
* Uma **Log Analytics workspace** no grupo de recursos que escolher — ou o seu workspace existente, se indicar um
* Três tabelas personalizadas nesse workspace: `RJAuditLogs_CL`, `RJOperationalLogs_CL`, `RJRunbookLogs_CL`
* Uma Data Collection Rule por tabela (`dcr-rj-aud-logs-*`, `dcr-rj-op-logs-*`, `dcr-rj-rb-logs-*`), cada uma com o seu próprio ponto final de ingestão direta
* Exatamente dois tipos de atribuição de função para o RealmJoin, e nada além disso:
  * **Leitor do Log Analytics** no workspace, para que o Portal possa consultar os seus registos
  * **Publicador de Métricas de Monitorização** em cada uma das três Data Collection Rules, para que o RealmJoin possa escrever nelas

O RealmJoin não recebe nenhuma outra permissão na sua subscrição. Não há registo de aplicação, segredo de cliente nem chave partilhada do workspace envolvidos. A implementação é idempotente — voltar a executar o mesmo comando é seguro e aplica apenas o que está em falta.

## Pré-requisitos

### No Portal RealmJoin

* Uma função que concede acesso à área de Definições (`CanReadSettingsDetails`, consulte [Permissões Disponíveis](https://docs.realmjoin.com/pt/administracao-e-definicoes/permission/custom-roles/available-permissions.md)). A página de definições gera o comando de configuração incluindo um token de integração de curta duração.

### No Azure

* Uma subscrição Azure e uma **grupo de recursos existente** para implementação — o módulo não cria o grupo de recursos
* Opcionalmente, um Log Analytics workspace existente. Se não indicar um, será criado um workspace para si na região do grupo de recursos.

### Na máquina que executa o PowerShell

* **PowerShell 5.1** ou posterior (Windows PowerShell ou PowerShell 7)
* Acesso à [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin) para instalar o módulo RealmJoin
* O `Az.Accounts`, `Az.Resources` e `Az.Automation` módulos — o módulo RealmJoin instala-os automaticamente nas versões fixadas, para o utilizador atual

### Permissões da conta com a qual inicia sessão

* **Microsoft Entra ID:** permissão para criar service principals, por exemplo *Administrador de Aplicações*, *Administrador de Aplicações na Cloud* ou *Administrador Global*. Só é necessário na primeira vez, quando o service principal dos Recursos Azure do RealmJoin ainda não existe.
* **subscrição Azure:** permissão para implementar no grupo de recursos **e** para criar atribuições de função nele — por exemplo *Proprietário*, ou *Contribuidor* combinado com *Administrador de Acesso de Utilizador* / *Administrador de Controlo de Acesso Baseado em Funções*.
* O início de sessão ocorre através de `Connect-AzAccount`, que usa a aplicação **Azure PowerShell** de primeira parte. Tenants que restrinjam o consentimento do utilizador podem ter de conceder primeiro consentimento de administrador a essa aplicação.

{% hint style="warning" %}
Execute o comando numa **sessão local recém-aberta** sessão do PowerShell e evite **Azure Cloud Shell**. O módulo RealmJoin requer versões exatas dos módulos `Az.*` módulos. Se já estiver carregada uma versão diferente na sessão — o que normalmente acontece no Cloud Shell — o módulo termina com um conflito de versões que só pode ser resolvido ao abrir uma nova sessão.
{% endhint %}

## Configuração

{% stepper %}
{% step %}

#### Prepare o grupo de recursos

No Azure Portal, crie ou selecione o grupo de recursos que deve alojar o workspace. Anote o respetivo nome e o ID da subscrição em que se encontra.

Se pretender usar um **existente** Log Analytics workspace, anote também o respetivo nome.
{% endstep %}

{% step %}

#### Copie o comando do RealmJoin Portal

No RealmJoin Portal, navegue até **Definições → Log Analytics** (<https://portal.realmjoin.com/settings/log-analytics-configuration>).

A página indica que o Log Analytics é gerido através do módulo RealmJoin PowerShell e mostra um bloco de comando. Use o **Copiar** para o copiar.

```powershell
$latest = [version](Find-Module RealmJoin -Repository PSGallery -ErrorAction Stop).Version
if (-not (Get-Module -ListAvailable RealmJoin | Where-Object Version -ge $latest)) {
    Install-Module RealmJoin -Force -AllowClobber -ErrorAction Stop
}
Import-Module RealmJoin -Force
Set-RJLogAnalyticsWorkspace -Token "<Token>" 6>&1
```

As primeiras linhas instalam ou atualizam o módulo RealmJoin e importam-no. `Set-RJLogAnalyticsWorkspace` efetua a implementação e regista o resultado com o RealmJoin usando o `-Token`.

{% hint style="info" %}
**Sobre `6>&1`:** estes comandos comunicam o seu progresso no fluxo de Informação do PowerShell. A `6>&1` redireção mostra essa saída na consola — sem ela não verá quaisquer mensagens de progresso.
{% endhint %}
{% endstep %}

{% step %}

#### Adicione os parâmetros de destino

`Set-RJLogAnalyticsWorkspace` precisa de saber onde implementar. Preencha a última linha antes de o executar:

```powershell
Set-RJLogAnalyticsWorkspace -ResourceGroupName "rg-realmjoin" -SubscriptionId "<SubscriptionId>" -Token "<Token>" 6>&1
```

* `-ResourceGroupName` é obrigatório. Se o omitir, o PowerShell pedir-lho-á.
* `-SubscriptionId` é opcional — sem ele, é usada a subscrição do seu contexto Azure atual e ser-lhe-á pedido que escolha se houver várias disponíveis.
* `-WorkspaceName` é opcional. Passe-o para definir o nome de um novo workspace ou para usar um **existente** workspace; caso contrário, será criado um novo com um nome gerado.
  {% endstep %}

{% step %}

#### Execute o comando

Cole o bloco numa nova sessão do PowerShell e execute-o. O token é válido por cerca de uma hora — se tiver expirado, recarregue a página de definições e copie novamente o comando.

Ser-lhe-á pedido para iniciar sessão com `Connect-AzAccount`. Se a sua conta tiver acesso a vários tenants ou subscrições, o módulo pede-lhe que escolha.

A implementação depois relata cada recurso à medida que é criado: o Service Principal, o workspace, as tabelas personalizadas, as Data Collection Rules e as atribuições de funções. Uma única execução normalmente demora alguns minutos.

{% hint style="info" %}
Quer ver primeiro o que aconteceria? Adicione `-WhatIf` para uma pré-visualização What-If do Azure Resource Manager. Note que o início de sessão e a instalação dos `Az` módulos continuam a acontecer, porque a pré-visualização precisa de ambos.
{% endhint %}

{% hint style="info" %}
**Terminar sessão depois:** o início de sessão do Azure mantém-se ativo depois de o comando terminar. Quando acabar, execute `Disconnect-AzAccount` para terminar sessão da sessão existente.
{% endhint %}
{% endstep %}

{% step %}

#### Verifique no Portal

Regresse a **Definições → Log Analytics** e selecione **Atualizar**.

A página mostra agora a subscrição, o grupo de recursos, o nome do workspace, o ID do workspace do cliente e o ID do Tenant como campos só de leitura — estas definições passam a ser mantidas pelo módulo PowerShell a partir de agora. Em **Avançadas** pode rever os pontos finais, nomes de regras e nomes de streams das três Data Collection Rules.

Selecione **Verifique se existem problemas de configuração** para confirmar que todas as permissões Azure necessárias estão em vigor no workspace e em cada Data Collection Rule.

Depois, abra o [Registo de Auditoria](https://docs.realmjoin.com/pt/monitorizacao-e-registos/audit-log.md) ou a [Registos de Runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-logs.md) e confirme que as entradas aparecem. O Azure precisa de alguns minutos para disponibilizar as tabelas personalizadas recém-criadas.
{% endstep %}
{% endstepper %}

## Retenção de dados

{% hint style="warning" %}
Para manter registos por mais de 30 dias, ajuste a [retenção de dados do workspace](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-retention-archive?tabs=portal-1%2Cportal-2) no Azure. Tanto a retenção predefinida do workspace como a retenção do Azure Automation são de 30 dias.
{% endhint %}

## Manter o esquema atualizado

Se o RealmJoin alargar o esquema de registos numa futura versão, a página de definições mostra um aviso de que o esquema do Log Analytics implementado está desatualizado, juntamente com o comando para o atualizar. Esse é o **mesmo** `Set-RJLogAnalyticsWorkspace` comando — volte a executá-lo e as tabelas e regras são atualizadas no local.

## Configuração legada (Data Collector API)

{% hint style="danger" %}
A configuração abaixo usa o Azure Monitor **API HTTP Data Collector**, cujo suporte a Microsoft termina em **14 de setembro de 2026**. Está documentado apenas para referência em tenants que foram configurados desta forma no passado. Não o use para novas configurações — siga a [Configuração](#setup) acima, ou [migrar uma configuração existente](https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-ingestion-api-migration.md).
{% endhint %}

<details>

<summary>Mostrar a configuração legada</summary>

Neste caminho, o RealmJoin autenticava-se com um registo de aplicação Entra ID propriedade do cliente e com a chave partilhada do workspace, e escrevia nas tabelas `AuditLogs_CL`, `OperationalLogs_CL` e `RunbookLogs_CL`.

**Parte 1 — Autenticação usando um registo de aplicação Azure**

1. No Azure Portal, navegue para Microsoft Entra ID > Gerir > Registos de aplicações.
2. Selecione o separador Todas as aplicações.
3. Reutilize o registo de aplicação "RealmJoin Runbooks Management" criado quando [runbooks de integração](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation.md), ou selecione "Novo registo" e registe uma nova aplicação.
4. Na aplicação, navegue para Gerir > Certificados e segredos, selecione o separador "Segredos de cliente" e crie um novo segredo de cliente. Defina a descrição e a expiração de acordo com as suas políticas internas de nomenclatura e segurança.
5. Anote o valor do segredo de forma segura — ao sair da página, o Azure obscurece-o e terá de ser criado um novo segredo.

**Parte 2 — Criar um Log Analytics workspace**

1. No Azure Portal, navegue para Log Analytics Workspace e selecione Criar.
2. Forneça um grupo de recursos, nome e região conforme necessário.
3. No separador "Visão geral", anote o nome do grupo de recursos, o nome do workspace e o ID do workspace.

**Parte 3 — Permissões no Azure**

1. Navegue até à subscrição em que o seu Log Analytics workspace se encontra.
2. Selecione Controlo de acesso (IAM) e adicione uma atribuição de função.
3. Conceda ao seu registo de aplicação **Monitoring Contributor** no workspace usado para os registos do RealmJoin.
4. Revise e guarde a atribuição de função.

**Parte 4 — Ligar o RealmJoin e o workspace**

No RealmJoin Portal, navegue para Definições > Log Analytics e preencha os campos:

* **TenantId** — o ID do seu tenant Entra ID, a partir da página Visão geral do Entra ID
* **ClientId** e **ClientSecret** — o registo de aplicação da Parte 1
* **ID da subscrição**, **Grupo de recursos** e **Nome do workspace** — do workspace da Parte 2
* **ID do workspace do cliente** — o ID do workspace que armazena os dados de auditoria e de registo dos runbooks do RealmJoin
* **Chave do workspace do cliente** — a "Primary Key" do workspace, que permite ao RealmJoin escrever dados. Pode ser obtida com o [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/monitor/log-analytics/workspace?view=azure-cli-latest#az-monitor-log-analytics-workspace-get-shared-keys) (`az monitor log-analytics workspace get-shared-keys --resource-group MyResourceGroup --workspace-name MyWorkspace`) ou com [PowerShell](https://learn.microsoft.com/en-us/powershell/module/az.operationalinsights/get-azoperationalinsightsworkspacesharedkey?view=azps-14.6.0) (`Get-AzOperationalInsightsWorkspaceSharedKey -ResourceGroupName "MyResourceGroup" -Name "MyWorkspace"`).

Prima **Guardar** depois de preencher todos os campos. O sistema dá-lhe feedback se tudo tiver corrido bem.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-analytics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
