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

# Integrate with the Azure Logs Ingestion API

> Send network traffic logs from ngrok to Azure Logs Ingestion.

This guide explains how to send ngrok events, including network traffic logs, to Azure via the Logs Ingestion API.

This is useful if you want to keep an audit log of configuration changes in your ngrok account, record all traffic to your endpoints for active monitoring and troubleshooting, or use it as a SIEM for security inspections.

By integrating ngrok with Azure, you can:

* Quickly identify application issues in real time using ngrok request events and Azure logs processing.
* Historically audit changes occurring in an account.
* Profile usage of your service using logs queries and real-time data analytics.
* Identify security issues using ngrok events.

## 1. Create a Log Analytics workspace

These steps were adapted from the Microsoft documentation for creating a Log Analytics workspace.

* In a browser, sign in to the Azure portal.
* In the search bar, type **Log Analytics Workspaces**.
* Click the **Services** entry (not the Marketplace entry).
* Click **Create** on the top bar of the Log Analytics Workspace page.
* Follow the wizard to create your Log Analytics Workspace, filling in the region, name, and resource group, then click **Review + Create**.
  These values can be anything you like and do not affect ngrok's ability to send logs to your Azure account.
* Click **Create** at the bottom of the review step to provision the Log Analytics Workspace.

You now have a **Log Analytics Workspace**, which will be the home for your data collection endpoint, tables, and rules.

## 2. Create a data collection endpoint

These steps were adapted from the Microsoft documentation for creating a data collection endpoint.

* In the search bar, type **Data Collection Endpoints**.
* Click the **Services** entry.
* Click **Create** on the top bar of the Data Collection Endpoints page.
* Follow the wizard to create your Data Collection Endpoint, filling in the region, name, and resource group, then click **Review + Create**.
  These fields can be anything you like and do not affect ngrok's ability to send logs to your Azure account.
* Click **Create** at the bottom of the review step to provision the Data Collection Endpoint.

You now have a **Data Collection Endpoint**, which is the network-accessible service that ngrok uses to send events to Azure.

## 3. Create a DCR-based custom table in the workspace

These steps were adapted from the Microsoft documentation for creating a new table in a Log Analytics workspace.

* Navigate to the **Log Analytics Workspaces** list again.
* Click the workspace you created in [Step 1](#1-create-a-log-analytics-workspace).
* In the sidebar of the selected workspace, go to **Settings** > **Tables**.
* Click **Create** on the top bar and click **New custom log (DCR-based)**.
* Populate the table name with a name of your choice and the DCE field with the existing DCE you created in [Step 2](#2-create-a-data-collection-endpoint).
* Under the Data collection rule field, click **Create a new data collection rule**, which opens a drawer.
  Fill out the resource group and name, then click **Done** in the drawer.
* Click **Next** in the table creation wizard.
* Upload the following JSON file using the wizard.
  After uploading, you will see a warning header "TimeGenerated field is not found in the sample provided"; this is expected.

```json theme={null}
{
	"event_id": "ev_2iKcXvmLJoZojWzrCuLbstBCle0",
	"event_type": "test",
	"event_timestamp": "2024-06-24T15:25:52Z",
	"object": {}
}
```

<Tip>
  **Not to worry!**

  You will see a warning header "TimeGenerated field is not found in the sample provided"; this is expected.
  You can fix this using the **Transformation Editor**.
</Tip>

* Click the **Transformation editor** button on the top bar of the wizard to open a drawer.
* Paste in the following transformation and click **Run**.

```
source
| extend TimeGenerated = event_timestamp
```

* Click **Apply**, then **Next**, then **Create**.

You now have a **Data Collection Rule** configured for ngrok events, along with a table where the data will be stored.

## 4. Create a Microsoft Entra Application

These steps were adapted from the Microsoft documentation for creating a Microsoft Entra Application.

* In the search bar, type **Microsoft Entra ID**.
* Under **Services**, click **Microsoft Entra ID** (not the Marketplace item).
* In the sidebar, go to **Manage** > **App registrations**.
* Click **New registration**.
* Name the application **ngrok-events** or something similar to clarify its use; this entity is what ngrok uses to authenticate with your data collection endpoint.
* For account type, choose **Accounts in this organizational directory only**.
* Click **Register**.

You have now created a **Microsoft Entra ID App Registration**, which is a service principal that grants roles and access to services like ngrok.

## 5. Assign IAM permissions to the Application for the DCR

These steps were adapted from the Microsoft documentation for assigning permissions to the DCR.

* In the search bar, type **Data collection rules**.
* Under **Services**, click **Data collection rules**.
* Click the Data collection rule you created in [Step 3](#3-create-a-dcr-based-custom-table-in-the-workspace).
* In the sidebar, click **Access control (IAM)**.
* Click **Add** on the top bar.
* Click **Add role assignment**.
* Under **Job function roles**, search for **Monitoring**.
* Click **Monitoring Metrics Publisher**.
* Click **Next** to go to Members.
* Click **Select members**.
* Search for the app registration you created in [Step 4](#4-create-a-microsoft-entra-application).
* Click the service principal and click **Select**.
* Click **Review + assign**, then **Review + assign** again to confirm the role assignment.

You have now granted the ngrok application access to ingest logs into the DCR, which is the final step before creating an Event Destination.

## 6. Gather necessary data for event destination

To create an event destination in the ngrok dashboard, gather the following from what you created in Azure:

* Tenant ID

* Application's Client ID

* Application's Client Secret

* DCR immutable ID

* DCR stream name

* DCE log ingestion URI

* To get the first three fields, go back to **Microsoft Entra ID**.
  In the top search bar, search for **Entra** and click **Microsoft Entra ID**.

* In the sidebar, go to **Manage** > **App registrations** and click the application you created in [Step 4](#4-create-a-microsoft-entra-application).

* On the Overview page, copy **Application (client) ID** and **Directory (tenant) ID**.

* In the sidebar, go to **Manage** > **Certificates & secrets**.

* Click **New client secret**.

* Fill in the description and expiry date, then click **Add**.

* Copy the secret value provided by Azure.
  This value is only shown once; it will not be available after you navigate away.

* To get the DCR immutable ID and stream name, navigate to **Data collection rules** using the top search bar.

* Click the Data collection rule you created in [Step 3](#3-create-a-dcr-based-custom-table-in-the-workspace).

* In the **Overview** tab, copy the **Immutable Id** value.

* In the sidebar, go to **Configuration** > **Data sources**.

* Copy the **Data source** name, which starts with "Custom-" (for example, `Custom-NgrokEvents_CL`).
  This is the **DCR stream name**.
  Use this value exactly as shown in Azure; passing a different format (such as the table name) results in a `400 InvalidStream` error from the Logs Ingestion API.

* In the top search bar, navigate to **Data collection endpoints**.

* Click the Data collection endpoint you created in [Step 2](#2-create-a-data-collection-endpoint).

* In the **Overview** tab, copy the **Logs Ingestion URI**.

You now have all the required data to create an event destination with ngrok.

## 7. Create the new event destination in ngrok

At this point, you can create the event destination [through the ngrok dashboard](#creating-through-the-ngrok-dashboard) or [via the ngrok API](#creating-via-the-ngrok-api).

### Creating through the ngrok dashboard

* Sign in to the ngrok dashboard and go to [**Log Exporting**](https://dashboard.ngrok.com/log-exporting).
* Click **+ New Log Export**.
* In the **Sources** tab, click **Add Source** to choose which events to send to Azure.

<Tip>
  To capture traffic events only from specific endpoints or tunnels, add a CEL filter expression when configuring the source.
  For example, to filter by hostname: `ev.conn.server_name == "your-tunnel.ngrok.app"`.
  See [Log Sources filters](/obs/events#filters) for more examples and filter syntax.
</Tip>

* In the **Destinations** tab, click **Add Destination**.
* Click **Azure Logs Ingestion API**.
* Fill in the fields using the values you collected in Step 6.
* Click **Send Test Event** and look for an example event in your Azure account.
  It may take a minute to appear due to propagation delays.
* Click **Done** and save the new Log Export.

### Creating via the ngrok API

* Create an API key with ngrok (for example via the ngrok dashboard).
* Using your REST API tool of choice (cURL, Postman, etc.), run the following API calls.
* To create the Azure Logs Ingestion event destination, run:

```bash theme={null}
curl --location 'https://api.ngrok.com/event_destinations' \
--header 'Accept: application/json' \
--header 'Ngrok-Version: 2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_KEY}' \
--data '{
    "format": "json",
    "target": {
        "azure_logs_ingestion": {
            "tenant_id":     "{TENANT_ID}",
		      "client_id":     "{CLIENT_ID}",
		      "client_secret": "{CLIENT_SECRET}",

		      "logs_ingestion_uri":          "{DCE_LOGS_INGESTION_URI}",
		      "data_collection_rule_id":     "{DCR_RULE_ID}",
		      "data_collection_stream_name": "{DCR_STREAM_NAME}"
         }
    }
}'
```

Copy the returned event destination ID from the response.

* To create a log export (event subscription) using the event destination you created, run:

```bash theme={null}
curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{
   "description":"ip policy creations",
   "destination_ids":["{EVENT_DESTINATION_ID}"],
   "sources":[
      {"type":"ip_policy_created.v0"},
      {"type":"{MORE_EVENT_TYPES}"}
   ]
}' \
https://api.ngrok.com/event_subscriptions
```

After you get a 200 response, your event destination is configured and subscribed to the set of event types you specified.