> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure Access and Logging Runbook

> How to connect to Olis Azure environments and set up/operate centralized logging.

## Scope

This runbook covers:

1. Connecting to the Olis Azure environment safely.
2. Verifying the deployed Container Apps.
3. Setting up and validating centralized logging.
4. Running operational queries and alerts.

Use this for dev/qa/prod by swapping names and resource groups.

## Prerequisites

* Azure CLI (`az`) installed and authenticated.
* Access to the target subscription.
* RBAC roles (minimum):
  * `Reader` on resource group for viewing.
  * `Container App Contributor` for app/env changes.
  * `Key Vault Secrets User` for reading secret metadata/values.
  * `Monitoring Reader` (and `Monitoring Contributor` if creating alerts).

## Connect to Azure

```bash theme={null}
# 1) Sign in
az login

# 2) Select subscription
az account set --subscription "Azure subscription 1"

# 3) Set defaults (example: dev)
az configure --defaults group=rg-olis-dev-qa-prod location=eastus
```

Confirm identity and scope:

```bash theme={null}
az account show --query "{name:name,id:id,user:user.name}" -o table
az group show -n rg-olis-dev-qa-prod --query "{name:name,location:location}" -o table
```

## Validate Deployed Apps

Current dev app names used by this repo:

* Auth: `olis-auth-aca-wp`
* RAG: `olis-rag-dev-wp`
* Ingestion worker: `olis-ingest-worker-dev-wp`

```bash theme={null}
az containerapp list --query "[].{name:name,rg:resourceGroup,env:properties.managedEnvironmentId}" -o table

az containerapp show -n olis-auth-aca-wp \
  --query "{image:properties.template.containers[0].image,rev:properties.latestRevisionName,url:properties.configuration.ingress.fqdn}" -o json
```

## Logging Architecture

For Container Apps, baseline operational logging should be:

1. App writes structured logs to stdout/stderr.
2. Container Apps environment ships logs to Log Analytics.
3. Alert rules are created on KQL queries.

In this repo, the Log Analytics wiring pattern is defined in:

* `infra/main.bicep` (workspace creation)
* `infra/modules/containerapps_env.bicep` (managed env `appLogsConfiguration`)

## Verify Log Analytics Is Wired

Get managed environment details:

```bash theme={null}
az containerapp env show -n olis-cae-dev-wp \
  --query "{name:name,appLogs:properties.appLogsConfiguration}" -o json
```

Expected:

* `destination = "log-analytics"`
* `logAnalyticsConfiguration.customerId` populated

If this is missing, deploy/update environment with IaC from `infra/main.bicep` and `infra/modules/containerapps_env.bicep`.

## Live Log Access

Tail application logs:

```bash theme={null}
az containerapp logs show -n olis-auth-aca-wp --tail 200 --format text
az containerapp logs show -n olis-rag-dev-wp --tail 200 --format text
```

Tail a specific revision:

```bash theme={null}
az containerapp revision list -n olis-auth-aca-wp -o table
az containerapp logs show -n olis-auth-aca-wp --revision <revision-name> --tail 200 --format text
```

## KQL Queries (Log Analytics)

Find recent auth errors:

```kusto theme={null}
ContainerAppConsoleLogs_CL
| where ContainerAppName_s == "olis-auth-aca-wp"
| where TimeGenerated > ago(30m)
| where Log_s has_any ("ERROR", "Traceback", "HTTPException")
| project TimeGenerated, ContainerAppName_s, Log_s
| order by TimeGenerated desc
```

Find seat/invite/email auth activity:

```kusto theme={null}
ContainerAppConsoleLogs_CL
| where ContainerAppName_s == "olis-auth-aca-wp"
| where TimeGenerated > ago(2h)
| where Log_s has_any ("/org/users/invite", "/org/seat-requests", "/auth/email/start", "/auth/email/verify-code", "/auth/email/exchange")
| project TimeGenerated, Log_s
| order by TimeGenerated desc
```

Container restart/system issues:

```kusto theme={null}
ContainerAppSystemLogs_CL
| where TimeGenerated > ago(2h)
| where ContainerAppName_s in ("olis-auth-aca-wp", "olis-rag-dev-wp", "olis-ingest-worker-dev-wp")
| project TimeGenerated, ContainerAppName_s, Reason_s, Log_s
| order by TimeGenerated desc
```

## Create Basic Alert Rules

Create an alert for repeated auth errors (example):

```bash theme={null}
az monitor scheduled-query create \
  --name "olis-auth-errors-dev" \
  --resource-group rg-olis-dev-qa-prod \
  --scopes "/subscriptions/<sub-id>/resourceGroups/rg-olis-dev-qa-prod/providers/Microsoft.OperationalInsights/workspaces/olis-law-dev" \
  --condition "count 'ContainerAppConsoleLogs_CL | where ContainerAppName_s == \"olis-auth-aca-wp\" | where Log_s has \"ERROR\"' > 5" \
  --evaluation-frequency 5m \
  --window-size 5m \
  --severity 2
```

Add action groups after creating your notification channel(s).

## Optional: App Insights for Request Traces

If you want richer request traces/metrics in addition to container logs:

1. Create a workspace-based Application Insights resource.
2. Store the connection string in Key Vault.
3. Expose it to the auth/rag containers as env var `APPLICATIONINSIGHTS_CONNECTION_STRING`.
4. Add SDK instrumentation in services if needed.

Note: Container logs to Log Analytics remain the primary operational baseline.

## Key Vault Checks (SMTP + Auth)

Example checks for current auth prefix:

```bash theme={null}
az keyvault secret show --vault-name olis-kv-dev -n olis-auth-aca-wp-notifier-from-email --query "{name:name,updated:attributes.updated}" -o json
az keyvault secret show --vault-name olis-kv-dev -n olis-auth-aca-wp-smtp-host --query "{name:name,updated:attributes.updated}" -o json
az keyvault secret show --vault-name olis-kv-dev -n olis-auth-aca-wp-smtp-username --query "{name:name,updated:attributes.updated}" -o json
```

## Smoke Checklist After Deployment

1. Auth app revision updated and healthy.
2. `NOTIFIER_PROVIDER=smtp` and `AUTH_EMAIL_ENABLED=true` present in env.
3. Invite call returns notification `{ sent: true }`.
4. Seat request call returns notification `{ sent: true }`.
5. Email code verification returns access token.
6. Magic link flow returns grant and exchange returns access token.
7. Logs appear in Container Apps logs and Log Analytics queries.

## Troubleshooting

* `403 ORG_NOT_FOUND` on email start:
  * Domain identity is not mapped in `org_identities` for that org.
* `500` on invite/seat APIs:
  * Check auth app logs first, then confirm org/membership rows and DB connectivity.
* `Handshake 429` from `az containerapp exec`:
  * Retry after short delay; exec endpoint is rate-limited.
* SMTP notifications not sending:
  * Validate Key Vault secret refs, sender domain, and SMTP credentials.