Application Logs

This page covers deployments running in your own Azure subscription (managed by us or by you). For an on-premises Docker install, see Application Logs (On-Premises).

Because the infrastructure runs in your subscription, you already have full access to every log line. Nothing extra needs to be installed, and there is no separate log CLI: you read the logs with the Azure tools you already have.

Where your logs live

The application and its workflow workers write to standard output. Azure Container Apps ships that output to the Log Analytics workspace in your resource group, where it lands in the ContainerAppConsoleLogs_CL table. Application-level traces and metrics also flow to Application Insights in the same resource group.

Two extra sources are worth knowing about:

• Azure Activity Log records every resource change, including each deployment. Use it to answer "what changed, and when".
• Processing history per transaction is in the product itself, not in the platform logs. Open a transaction and look at its history to see which steps ran and how long they took. That is usually the faster place to start for a single failed document.

Reading the logs

Live stream (Azure Portal)

Open your resource group, select the DocAI Fabric container app, then Monitoring → Log stream. This tails the running replica, which is the quickest way to watch a document being processed.

Live stream (Azure CLI)

az containerapp logs show \
  --name <your-container-app-name> \
  --resource-group <your-resource-group> \
  --follow

Querying history (Log Analytics)

The Portal path is Log Analytics workspace → Logs, then run a KQL query. The last 100 errors:

ContainerAppConsoleLogs_CL
| where TimeGenerated > ago(24h)
| where Log_s contains "ERROR"
| order by TimeGenerated desc
| take 100

Everything logged around one transaction (paste its ID):

ContainerAppConsoleLogs_CL
| where TimeGenerated > ago(7d)
| where Log_s contains "<transaction-id>"
| order by TimeGenerated asc
| project TimeGenerated, Log_s

The same query from a terminal:

az monitor log-analytics query \
  --workspace <your-log-analytics-workspace-id> \
  --analytics-query "ContainerAppConsoleLogs_CL | where Log_s contains 'ERROR' | order by TimeGenerated desc | take 100"

Log Analytics is not instant: expect a delay of a minute or two before a new line becomes queryable. Use the live stream when you need to see something as it happens.

What to look for

Every line is prefixed with a level (INFO, WARNING, ERROR). When you report an issue to us, the fastest thing to send is the last ERROR block plus the few lines above it, which usually name the transaction or the processing step that failed. You never need to share a whole log.

Retention

Log Analytics is provisioned with the default retention of 30 days. Azure Activity Log is retained for 90 days at the subscription level automatically.

If you need longer retention for compliance reasons, options include:

• Raising the Log Analytics retention to up to 730 days (incurs additional cost)
• Configuring continuous export to a Storage Account for indefinite archival
• Enabling the Log Analytics archive tier for low-cost long-term storage

Let us know your requirements and we can configure this when deploying or update it later.

Shared Log Access for Our Support Team

We strongly recommend granting our team read-only access to logs so we can diagnose issues quickly without asking you to copy/paste excerpts on every support ticket.

For managed deployments (we operate the CI/CD pipeline), no action is needed from you. With your consent, given once during onboarding or on a support ticket, our deployment pipeline registers the Azure Lighthouse delegation automatically as part of a regular deployment. Option A below describes exactly what gets granted, so your security team can review it before consenting, and how to revoke it. One exception: if our pipeline's service principal is scoped to a single resource group (the default for existing-subscription setups), automatic registration is not possible and we will ask you to run the one-line command from Option A instead.

If you prefer to review and run the registration yourself, follow Option A directly. Option B is a fallback for organisations whose policy forbids cross-tenant delegation entirely. Both options are read-only, scoped to your DocAI Fabric resource group only, and fully revocable.

Option	Best for	Identity in your tenant?	Setup effort
Azure Lighthouse (preferred)	Strict enterprises, multi-customer relationships	No (projected from our tenant)	One ARM deployment
Guest user + RBAC	Simpler one-customer setup, faster to grant today	Yes (guest user object)	Portal clicks, no template

Option A: Azure Lighthouse

Microsoft's purpose-built mechanism for managed service providers. Our identities are projected into your resource scope without appearing in your Entra directory. This is the same delegation our pipeline registers automatically for managed deployments; the template below is exactly what gets deployed, whichever path is used.

How it works:

• You run one command to authorise our Azure tenant with read-only access scoped to your resource group
• We query logs from our own Azure Portal; no credentials are shared, nothing is stored on our side
• The authorisation is fully visible in your Azure Activity Log
• You can revoke it at any time

Setup. The authorisation template is published at:

https://app.docaifabric.com/docs/lighthouse/log-access-delegation.json

It is fully self-describing: it names our tenant, the single support group being authorised, and the three read-only role IDs, so your security team can review exactly what is granted before deploying. It contains no secrets and grants nothing by itself; it only takes effect when deployed by an Owner of your subscription.

A user with Owner rights on your subscription (required for registering the delegation) runs:

az deployment sub create \
  --name docai-fabric-support-access \
  --location <YOUR_REGION> \
  --template-uri "https://app.docaifabric.com/docs/lighthouse/log-access-delegation.json" \
  --parameters rgName=<your-docai-resource-group>

If your policy requires deploying from a reviewed local copy, download the file first and pass --template-file log-access-delegation.json instead of --template-uri.

This grants our team Log Analytics Reader, Monitoring Reader, and Reader on your resource group only: no write access, no access to your documents, storage contents, or any other resources.

Revoking access:

az managedservices assignment list --query "[].id" -o tsv | \
  xargs -I {} az managedservices assignment delete --assignment {}

Or remove the delegation from the Azure Portal under Azure Lighthouse → Service providers.

Option B: Guest User + RBAC

Simpler if you only have one provider relationship and don't want to author a Lighthouse template. We share an email address; you invite it as a guest in your Entra ID and grant three read-only roles scoped to the resource group.

Steps:

1. Invite our support account as a guest user in your Entra ID:

   • Azure Portal → Microsoft Entra ID → Users → + New user → Invite external user
   • Use the email address we provide

2. Assign three built-in roles, scoped only to the DocAI Fabric resource group:

   Role	Purpose
   Reader	View container app configuration, revisions, storage listings
   Log Analytics Reader	Run KQL queries against the workspace
   Monitoring Reader	Access Application Insights, metrics, alerts, Activity Log

   Via Portal: open the DocAI resource group → Access control (IAM) → + Add role assignment → repeat for each role.

   Or via CLI:

   RG="<your-docai-resource-group>"
   USER_ID=$(az ad user list --filter "mail eq '<email-we-provide>'" --query "[0].id" -o tsv)
   SCOPE=$(az group show -n $RG --query id -o tsv)
   
   for ROLE in "Reader" "Log Analytics Reader" "Monitoring Reader"; do
     az role assignment create --assignee-object-id $USER_ID --role "$ROLE" --scope $SCOPE
   done

Revoking access: remove the role assignments from the resource group's IAM blade, or delete the guest user from Entra ID. Both actions appear in your Activity Log.

Safe on shared subscriptions. Because all three roles are assigned at resource group scope, the guest user cannot see or access any other resource group, any subscription-level resources, or other workloads sharing the subscription. The roles are pure read, with no ability to modify, deploy, or delete anything.

Conditional Access caveat. Guest users sign in through your tenant, so your Conditional Access policies apply to them. Policies that require a compliant or domain-joined device (or otherwise restrict external identities) will block our CLI and API access even after the roles are granted. If your organisation enforces such policies for guests, use Option A instead: Lighthouse identities authenticate in our tenant and are not subject to your guest sign-in policies, while remaining just as scoped, auditable, and revocable.

Tightening guest user defaults (optional). By default, guest users in Entra ID can see other users and groups in your directory (names only, no data). If your security policy is strict, you can set Entra ID → External identities → External collaboration settings → Guest user access to "Guest user access is restricted to properties and memberships of their own directory objects" before inviting.

Security (both options)

• Read-only: we cannot modify, delete, or access any resources
• Scoped to your resource group: no access to other RGs, other workloads, or subscription-level resources
• Auditable: every action we take appears in your Azure Activity Log
• Revocable: you can remove access at any time with a single command

If you prefer not to grant ongoing access, you can always share log excerpts manually, but expect slower turnaround on support.