---
title: Troubleshooting Elastic Cloud Forwarder for Azure
description: Diagnose and resolve issues with Elastic Cloud Forwarder for Azure using Azure Monitor and Application Insights.
url: https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/troubleshooting
products:
  - Elastic Cloud Forwarder
  - Elastic Cloud Forwarder for Azure
  - Elastic Cloud Serverless
  - Elastic Observability
applies_to:
  - Serverless Observability projects: Preview
  - Serverless Security projects: Preview
  - Elastic Cloud Forwarder for Azure: Preview since 0.7
---

# Troubleshooting Elastic Cloud Forwarder for Azure
This page helps you diagnose and resolve issues with Elastic Cloud Forwarder for Azure when data is not being forwarded to Elasticsearch as expected. To do so, Elastic Cloud Forwarder for Azure relies on native Azure platform features, specifically Azure Monitor and Application Insights.

## Key indicators for identifying failures

The following metrics are crucial for diagnosing issues, as they focus on identifying failures or possible performance issues in the processing pipeline:

| Indicator                                     | Source                             | Why it matters                                                                                                                                                                                                                                                                                                                       |
|-----------------------------------------------|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **IncomingMessages** and **OutgoingMessages** | Event Hub                          | A significant gap between the number of incoming and outgoing messages indicates the Function App is not consuming messages at the expected rate.                                                                                                                                                                                    |
| **Function Execution Failures**               | Application Insights → Metrics     | Non-zero values indicate the Function App is failing to process messages.                                                                                                                                                                                                                                                            |
| **AverageMemoryWorkingSet**                   | Function App                       | High usage precedes OOM errors, signaling resource limits or memory leaks before they cause failures. If memory remains high over time, review [Sizing and performance tuning for Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/sizing-performance-tuning-cost). |
| **Failures view**                             | Application Insights → Investigate | A rising error rate points to application-level defects that need immediate attention.                                                                                                                                                                                                                                               |
| **Error container blobs**                     | Storage account                    | Presence of `ecf-errors-logs` or `ecf-errors-metrics` containers confirms that deliveries to Elasticsearch are failing.                                                                                                                                                                                                              |


## General troubleshooting

As a first step, review the logs and metrics provided by the Azure platform. The following Elastic Cloud Forwarder components provide useful information about data processing.

### Event Hub

Go to your Elastic Cloud Forwarder resource group and find the **Event Hubs Namespace** resource to verify the health of the entry point:
- **Throughput:** Compare the number of **Incoming Messages** with **Outgoing Messages**. A significant gap suggests the Function App is not consuming messages at the expected rate. For partition and capacity guidance, refer to [Sizing and performance tuning for Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/sizing-performance-tuning-cost).
- **Throttling:** Monitor **Throttled Requests**. If you hit your Throughput Units (TUs), Event Hub will reject incoming telemetry from your sources. If throttling persists, review the Event Hub sizing guidance in [Sizing and performance tuning for Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/sizing-performance-tuning-cost).


### Function App

Navigate to your Elastic Cloud Forwarder resource group and find the **Function App** resource.
- **Invocations:** Go to **Functions** → **[Name]** → **Invocations** to verify if the trigger is firing. Here you can see overall counters of successful and unsuccessful invocations. To access data about the function execution over time, check the **Metrics** tab.
  <note>
  This view can have a reporting delay. Use this for auditing past trends rather than real-time troubleshooting. For immediate feedback, use **Live Metrics**.
  </note>
- **Live Metrics:** Located under **Monitoring** → **Application Insights** → **Investigate** → **Live Metrics**. Use this for real-time debugging during a suspected outage. It shows instantaneous CPU/Memory spikes, dependency failures, incoming request rate, duration, and number of failed requests. If duration or memory trends stay elevated, refer to [Sizing and performance tuning for Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/sizing-performance-tuning-cost).
- **Failures:** Located under **Investigate** → **Failures** in Application Insights. It provides a list of all failed operations with the option to drill into each one.
- **Logs:** Located under **Logs** in Application Insights. This provides a searchable history of all traces and exceptions across every instance of your Function App.


### Storage account

Navigate to your Elastic Cloud Forwarder resource group and find the **Storage account** resource.
If Elastic Cloud Forwarder is unable to process or deliver signals to Elasticsearch, it persists the batch as a blob in `ecf-errors-logs` or `ecf-errors-metrics` containers. These containers are created only upon the first failure.
<tip>
  Use the `ecf-replay-cli` tool to resubmit individual blobs back to Event Hub so they are picked up by Elastic Cloud Forwarder and forwarded to Elasticsearch again. Refer to [Resubmit failed events](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/replay-failed-events).
</tip>

Although the **Blob Count** metric exists, its utility is limited because it aggregates hourly.

## Telemetry data not appearing in Elasticsearch

This section helps you diagnose and resolve issues when Elastic Cloud Forwarder for Azure is deployed but telemetry data is not appearing in Elasticsearch.

### Symptoms

- Logs or metrics are not appearing in Elasticsearch or Kibana dashboards.
- The storage account contains unprocessed messages in error containers (`ecf-errors-logs` or `ecf-errors-metrics`).
- Function App execution logs in Application Insights show errors.
- Function App **Invocations** → **Error count** is non-zero or increasing.
- The Event Hub metrics show messages are being received but not processed.


### Diagnosis

Using the [key indicators](#key-indicators-for-identifying-failures) and [general troubleshooting](#general-troubleshooting) guidance above, check the following to identify the root cause:
1. **Verify Event Hub is receiving data**: Check the **Incoming Messages** metric. If no messages are arriving, the issue is with the diagnostic setting or the Data Collection Rule configuration.
2. **Compare Incoming and Outgoing Messages**: A significant gap between the number of incoming and outgoing messages confirms the Function App is not consuming messages at the expected rate.
3. **Check Function App logs**: Review execution logs in Application Insights for errors related to authentication, network connectivity, or data processing.
4. **Inspect error containers**: Check if failed messages are accumulating in `ecf-errors-logs` or `ecf-errors-metrics`.


### Resolution

<stepper>
  <step title="Verify the OTLP endpoint configuration">
    Confirm that the `ELASTICSEARCH_OTLP_ENDPOINT` environment variable is correct and the endpoint is accessible from the Function App.
    1. In the Azure portal, navigate to the Function App.
    2. Go to **Settings** → **Environment variables**.
    3. Verify the OTLP endpoint value matches your Elastic Cloud Serverless or Elastic Cloud Hosted endpoint.
  </step>

  <step title="Verify the API key">
    Confirm that the `ELASTICSEARCH_API_KEY` is valid and not expired.
    1. Check that the API key was trimmed correctly (only `MYKEYVALUE...`, not `Authorization=ApiKey MYKEYVALUE...`).
    2. Verify the API key has not expired in your Elastic Cloud deployment or Serverless project.
  </step>

  <step title="Verify the diagnostic setting or Data Collection Rule">
    Confirm the telemetry source is correctly configured to stream to the Event Hub.
    1. For Activity logs, verify the diagnostic setting is active and streaming to the correct Event Hub namespace and `logs` event hub.
    2. Ensure the Event Hub namespace is in the same region as the resources generating the telemetry.
  </step>

  <step title="Verify Event Hub metrics">
    Confirm the Event Hub is successfully passing data to the Function App and not showing throughput or throttling issues.
    1. Compare the number of **Incoming Messages** and **Outgoing Messages**. They should be the same or very close. If there is a significant gap, the Function App is not consuming messages at the expected rate. Continue to the next steps.
    2. Check for **Throttled Requests** that may indicate the Event Hub is rejecting incoming telemetry.
  </step>

  <step title="Check Function App invocations and metrics">
    Confirm there are no failing invocations.
    1. In the Azure portal, navigate to the Function App.
    2. Open the `logs` function and go to **Invocations**.
    3. Check the **Error** counter and review invocation details for recent failures.

    <note>
      This view might have a significant reporting delay. If you are currently deploying changes or investigating an active incident, proceed to the next step for real-time data.
    </note>
  </step>

  <step title="Check Application Insights failures and Live Metrics">
    Confirm there are no errors or exceptions, and monitor real-time health.
    1. In the Azure portal, navigate to the **Function App** → **Monitoring** → **Application Insights** → **Investigate**.
    2. Go to **Live Metrics** to see incoming request rate, duration, and number of failed requests in real time. Watch the memory consumption, as high usage may precede OOM errors.
    3. Go to **Failures** to confirm that no errors or exceptions are occurring.
    4. If the function is healthy but consistently close to its runtime or resource limits, review [Sizing and performance tuning for Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/sizing-performance-tuning-cost) for guidance on partition count, instance memory, instance count, and Event Hubs capacity.
  </step>

  <step title="Review Function App logs">
    Check Application Insights for specific error messages.
    1. In the Azure portal, navigate to the Application Insights resource created by the deployment.
    2. Go to **Logs** and query for Function App logs.
    3. Look for authentication failures, network errors, or data processing issues.
    The following KQL query helps structure logs for easier analysis:
    <dropdown title="KQL query to structure Function App logs">
      ```
      traces
      | extend parsed = parse_json(message)
      | extend logMessage = coalesce(tostring(parsed.message), message)
      | extend caller = parsed.caller
      | extend componentId = parsed.["otelcol.component.id"]
      | extend componentKind = parsed.["otelcol.component.kind"]
      | extend stackTrace = parsed.stacktrace
      | project timestamp, severityLevel, logMessage, caller, componentId, componentKind, stackTrace
      ```
    </dropdown>
    To quickly identify errors and warnings, use this query:
    <dropdown title="KQL query to filter non-informational logs">
      ```
      traces
      | where severityLevel != 1
      | project timestamp, severityLevel, message
      | order by timestamp asc
      ```
    </dropdown>
    If you need to be more specific, you can filter for particular symptoms. For example, use the following query to check for 503 Service Unavailable errors:
    <dropdown title="KQL query to filter 503 errors">
      ```
      traces
      | where severityLevel != 1 and message has "503"
      | project timestamp, severityLevel, message
      | order by timestamp asc
      ```
    </dropdown>
  </step>
</stepper>


## Resources

- [Configure Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/configure)
- [Deploy Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/deploy)
- [Sizing and performance tuning for Elastic Cloud Forwarder for Azure](https://www.elastic.co/docs/reference/opentelemetry/edot-cloud-forwarder/azure/sizing-performance-tuning-cost)
- [Contact support](https://docs-demo.elastic.dev/docs/troubleshoot)