Troubleshoot Azure Stream Analytics by using resource logs

  • Article

Occasionally, an Azure Stream Analytics job unexpectedly stops processing. It's important to be able to troubleshoot this kind of event. Failures can be caused by an unexpected query result, by connectivity to devices, or by an unexpected service outage. The resource logs in Stream Analytics can help you identify the cause of issues when they occur and reduce recovery time.

It's highly recommended to enable resource logs for all jobs as it will greatly help with debugging and monitoring.

Log types

Stream Analytics offers two types of logs:

  • Activity logs (always on), which give insights into operations performed on jobs.

  • Resource logs (configurable), which provide richer insights into everything that happens with a job. Resource logs start when the job is created and end when the job is deleted. They cover events when the job is updated and while it’s running.

Note

You can use services like Azure Storage, Azure Event Hubs, and Azure Monitor logs to analyze nonconforming data. You are charged based on the pricing model for those services.

Note

This article was recently updated to use the term Azure Monitor logs instead of Log Analytics. Log data is still stored in a Log Analytics workspace and is still collected and analyzed by the same Log Analytics service. We are updating the terminology to better reflect the role of logs in Azure Monitor. See Azure Monitor terminology changes for details.

Debugging using activity logs

Activity logs are on by default and give high-level insights into operations performed by your Stream Analytics job. Information present in activity logs may help find the root cause of the issues impacting your job. Do the following steps to use activity logs in Stream Analytics:

  1. Sign in to the Azure portal and select Activity log under Overview.

    Stream Analytics activity log

  2. You can see a list of operations that have been performed. Any operation that caused your job to fail has a red info bubble.

  3. Select an operation to see its summary view. Information here's often limited. To learn more details about the operation, select JSON.

    Stream Analytics activity log operation summary

  4. Scroll down to the Properties section of the JSON, which provides details of the error that caused the failed operation. In this example, the failure was due to a runtime error from out of bound latitude values. Discrepancy in the data that is processed by a Stream Analytics job causes a data error. You can learn about different input and output data errors and why they occur.

    JSON error details

  5. You can take corrective actions based on the error message in JSON. In this example, checks to ensure latitude value is between -90 degrees and 90 degrees need to be added to the query.

  6. If the error message in the Activity logs isn’t helpful in identifying root cause, enable resource logs and use Azure Monitor logs.

Send diagnostics to Azure Monitor logs

Turning on resource logs and sending them to Azure Monitor logs is highly recommended. They're off by default. To turn them on, complete these steps:

  1. Create a Log Analytics workspace if you don't already have one. It's recommended to have your Log Analytics workspace in the same region as your Stream Analytics job.

  2. Sign in to the Azure portal, and navigate to your Stream Analytics job. Under Monitoring, select Diagnostics logs. Then select Turn on diagnostics.

    Blade navigation to resource logs

  3. Provide a Name in Diagnostic settings name and check the boxes for Execution and Authoring under log, and AllMetrics under metric. Then select Send to Log Analytics and choose your workspace. Select Save.

    Settings for resources logs

  4. When your Stream Analytics job starts, resource logs are routed to your Log Analytics workspace. To view resource logs for your job, select Logs under the Monitoring section.

    Screenshot shows the General menu with Logs selected.

  5. Stream Analytics provides predefined queries that allow you to easily search for the logs that you're interested in. You can select any predefined queries on the left pane and then select Run. You'll see the results of the query in the bottom pane.

    Screenshot shows Logs for a Stream Analytics job.

Resource log categories

Azure Stream Analytics captures two categories of resource logs:

  • Authoring: Captures log events that are related to job authoring operations, such as job creation, adding and deleting inputs and outputs, adding and updating the query, and starting or stopping the job.

  • Execution: Captures events that occur during job execution.

    • Connectivity errors
    • Data processing errors, including:
      • Events that don�t conform to the query definition (mismatched field types and values, missing fields, and so on)
      • Expression evaluation errors
    • Other events and errors

All logs are stored in JSON format. To learn about the schema for resource logs, see Resource logs schema.

Next steps