Skip to content

Commit d84755d

Browse files
dlepowdlepow
committed
[APIM] Updates to Event Hub article
1 parent 8f338ac commit d84755d

File tree

1 file changed

+124
-43
lines changed

1 file changed

+124
-43
lines changed

‎articles/api-management/api-management-howto-log-event-hubs.md

Lines changed: 124 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,10 @@ description: Learn how to log events to Azure Event Hubs in Azure API Management
44
services: api-management
55
documentationcenter: ''
66
author: dlepow
7-
manager: erikre
8-
editor: ''
97

10-
ms.assetid: 88f6507d-7460-4eb2-bffd-76025b73f8c4
118
ms.service: api-management
12-
ms.workload: mobile
13-
ms.tgt_pltfrm: na
14-
ms.topic: article
15-
ms.date: 01/29/2018
9+
ms.topic: how-to
10+
ms.date: 12/20/2022
1611
ms.author: danlep
1712

1813
---
@@ -21,53 +16,139 @@ Azure Event Hubs is a highly scalable data ingress service that can ingest milli
2116

2217
This article describes how to log API Management events using Azure Event Hubs.
2318

24-
## Create an Azure Event Hub
19+
## Prerequisites
2520

26-
For detailed steps on how to create an event hub and get connection strings that you need to send and receive events to and from the Event Hub, see [Create an Event Hubs namespace and an event hub using the Azure portal](../event-hubs/event-hubs-create.md).
21+
* An API Management service instance. If you don't have one, see [Create an API Management service instance](get-started-create-service-instance.md).
22+
* An Azure Event Hubs namespace and event hub. For detailed steps, see [Create an Event Hubs namespace and an event hub using the Azure portal](../event-hubs/event-hubs-create.md).
23+
> [!NOTE]
24+
> The Event Hubs resource **can be** in a different subscription or even a different tenant than the API Management resource
25+
26+
## Configure access to the event hub
27+
28+
To log events to the event hub, you need credentials to enable access from API Management. API Management supports two access mechanisms: an Event Hubs connection string, or an API Management managed identity.
29+
30+
### Configure event hub connection string
31+
32+
To create an Event Hubs connection string, see [Get an Event Hubs connection string](../event-hubs/event-hubs-get-connection-string.md). You can get a connection string to the namespace or the specific event hub you use for logging from API Management
33+
34+
### Configure API Management managed identity
2735

2836
> [!NOTE]
29-
> The Event Hub resource **can be** in a different subscription or even a different tenant than the API Management resource
37+
> Using an API Management managed identity for logging events to an event hub is supported in API Management REST API version `2022-04-01-preview` or later.
38+
39+
1. Enable a system-assigned or user-assigned [managed identity for API Management](api-management-howto-use-managed-service-identity.md) in your API Management instance.
40+
41+
* If you enable a user-assigned managed identity, take note of the identity's **Client ID**.
42+
43+
1. Assign the identity the **Azure Event Hubs Data Owner** role, scoped to the Event Hubs namespace or to the event hub used for logging. To assign the role, use the [Azure portal](../active-directory/managed-identities-azure-resources/howto-assign-access-portal.md) or other Azure tools.
44+
3045

3146
## Create an API Management logger
32-
Now that you have an Event Hub, the next step is to configure a [Logger](/rest/api/apimanagement/current-ga/logger) in your API Management service so that it can log events to the Event Hub.
33-
34-
API Management loggers are configured using the [API Management REST API](/rest/api/apimanagement/ApiManagementREST/API-Management-REST). For detailed request examples, see [how to create Loggers](/rest/api/apimanagement/current-ga/logger/create-or-update).
35-
36-
## Configure log-to-eventhub policies
37-
38-
Once your logger is configured in API Management, you can configure your log-to-eventhub policy to log the desired events. The log-to-eventhub policy can be used in either the inbound policy section or the outbound policy section.
39-
40-
1. Browse to your APIM instance.
41-
2. Select the API tab.
42-
3. Select the API to which you want to add the policy. In this example, we're adding a policy to the **Echo API** in the **Unlimited** product.
43-
4. Select **All operations**.
44-
5. On the top of the screen, select the Design tab.
45-
6. In the Inbound or Outbound processing window, click the triangle (next to the pencil).
46-
7. Select the Code editor. For more information, see [How to set or edit policies](set-edit-policies.md).
47-
8. Position your cursor in the `inbound` or `outbound` policy section.
48-
9. In the window on the right, select **Advanced policies** > **Log to EventHub**. This inserts the `log-to-eventhub` policy statement template.
49-
50-
```xml
51-
<log-to-eventhub logger-id="logger-id">
52-
@{
53-
return new JObject(
54-
new JProperty("EventTime", DateTime.UtcNow.ToString()),
55-
new JProperty("ServiceName", context.Deployment.ServiceName),
56-
new JProperty("RequestId", context.RequestId),
57-
new JProperty("RequestIp", context.Request.IpAddress),
58-
new JProperty("OperationName", context.Operation.Name)
59-
).ToString();
47+
Now that you have an event hub, the next step is to configure a [Logger](/rest/api/apimanagement/current-ga/logger) in your API Management service so that it can log events to the event hub.
48+
49+
API Management loggers can be configured using the [API Management REST API](/rest/api/apimanagement/current-ga/logger/create-or-update) directly or tools including [Azure PowerShell](/powershell/module/az.apimanagement/new-azapimanagementlogger), a Bicep template, or an Azure Resource Management template.
50+
51+
### Logger with connection string credentials
52+
53+
#### [PowerShell](#tab/PowerShell)
54+
55+
The following example uses the [New-AzApiManagementLogger](/powershell/module/az.apimanagement/new-azapimanagementlogger) cmdlet to create a logger to an event hub by specifying a connection string.
56+
57+
```powershell
58+
# API Management service-specific details
59+
$apimServiceName = "apim-hello-world"
60+
$resourceGroupName = "myResourceGroup"
61+
62+
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName
63+
New-AzApiManagementLogger -Context $context -LoggerId "ContosoLogger1" -Name "ApimEventHub" -ConnectionString "Endpoint=sb://ContosoEventHubs.servicebus.windows.net/;SharedAccessKeyName=SendKey;SharedAccessKey=<key>" -Description "Event hub logger with connection string"
64+
```
65+
66+
#### [Bicep](#tab/bicep)
67+
68+
Include the following snippet in your Bicep template.
69+
70+
```Bicep
71+
@description('The name of the API Management service instance.')
72+
param serviceName string
73+
74+
resource apimService 'Microsoft.ApiManagement/service@2022-04-01-preview' existing = {
75+
name: serviceName
76+
77+
resource ehLoggerWithConnectionString 'Microsoft.ApiManagement/service/loggers@2022-04-01-preview' = {
78+
name: 'ContosoLogger1'
79+
parent: apimService
80+
properties: {
81+
loggerType: 'azureEventHub'
82+
description: 'Event hub logger with connection string'
83+
credentials: {
84+
connectionString: 'Endpoint=sb://ContosoEventHubs.servicebus.windows.net/;SharedAccessKeyName=SendKey;SharedAccessKey=<key>'
85+
name: 'ApimEventHub'
6086
}
61-
</log-to-eventhub>
87+
}
88+
}
89+
```
90+
91+
#### [ARM](#tab/arm)
92+
93+
Include the following JSON snippet in your Azure Resource Manager template.
94+
95+
```JSON
96+
{
97+
"type": "Microsoft.ApiManagement/service/loggers",
98+
"apiVersion": "2022-04-01-preview",
99+
"name": "ContosoLogger1",
100+
"properties": {
101+
"credentials": {
102+
"connectionString": "Endpoint=sb://ContosoEventHubs.servicebus.windows.net/;SharedAccessKeyName=SendKey;SharedAccessKey=<key>",
103+
"name": "ApimEventHub"
104+
},
105+
"description": "Event hub logger with connection string",
106+
"loggerType": "azureEventHub",
107+
"resourceId": "string"
108+
}
109+
}
62110
```
63-
Replace `logger-id` with the value you used for `{loggerId}` in the request URL to create the logger in the previous step.
111+
---
112+
113+
### Logger with system-assigned managed identity credentials
114+
115+
116+
### Logger with user-assigned managed identity credentials
117+
118+
119+
## Configure log-to-eventhub policy
120+
121+
Once your logger is configured in API Management, you can configure your [log-to-eventhub](api-management-advanced-policies.md#log-to-event-hub) policy to log the desired events. The `log-to-eventhub` policy can be used in either the inbound policy section or the outbound policy section.
122+
123+
1. Browse to your API Management instance.
124+
1. Select **APIs**, and then select the API to which you want to add the policy. In this example, we're adding a policy to the **Echo API** in the **Unlimited** product.
125+
1. Select **All operations**.
126+
1. On the top of the screen, select the **Design** tab.
127+
1. In the Inbound processing or Outbound processing window, select the `</>` (code editor) icon. For more information, see [How to set or edit policies](set-edit-policies.md).
128+
1. Position your cursor in the `inbound` or `outbound` policy section.
129+
1. In the window on the right, select **Advanced policies** > **Log to EventHub**. This inserts the `log-to-eventhub` policy statement template.
130+
131+
```xml
132+
<log-to-eventhub logger-id="logger-id">
133+
@{
134+
return new JObject(
135+
new JProperty("EventTime", DateTime.UtcNow.ToString()),
136+
new JProperty("ServiceName", context.Deployment.ServiceName),
137+
new JProperty("RequestId", context.RequestId),
138+
new JProperty("RequestIp", context.Request.IpAddress),
139+
new JProperty("OperationName", context.Operation.Name)
140+
).ToString();
141+
}
142+
</log-to-eventhub>
143+
```
64144

65-
You can use any expression that returns a string as the value for the `log-to-eventhub` element. In this example, a string in JSON format containing the date and time, service name, request ID, request IP address, and operation name is logged.
145+
1. Replace `logger-id` with the name of the logger that you created in the previous step.
146+
1. You can use any expression that returns a string as the value for the `log-to-eventhub` element. In this example, a string in JSON format containing the date and time, service name, request ID, request IP address, and operation name is logged.
66147

67-
Click **Save** to save the updated policy configuration. As soon as it is saved the policy is active and events are logged to the designated Event Hub.
148+
1. Select **Save** to save the updated policy configuration. As soon as it is saved, the policy is active and events are logged to the designated event hub.
68149

69150
> [!NOTE]
70-
> The maximum supported message size that can be sent to an event hub from this API Management policy is 200 kilobytes (KB). If a message that is sent to an event hub is larger than 200 KB, it will be automatically truncated, and the truncated message will be transferred to event hubs.
151+
> The maximum supported message size that can be sent to an event hub from this API Management policy is 200 kilobytes (KB). If a message that is sent to an event hub is larger than 200 KB, it will be automatically truncated, and the truncated message will be transferred to the event hub.
71152

72153
## Preview the log in Event Hubs by using Azure Stream Analytics
73154

0 commit comments

Comments
 (0)