Contents

On-premises data gateways

Overview
What is an on-premises data gateway?
Concepts
On-premises data gateway architecture
On-premises data gateway FAQ
How to
Install gateways
Configure gateways
Use the on-premises data gateway app
Configure proxy settings
Change the gateway service account
Set the data center region
Adjust communication settings
Configure the gateway log file
Manage gateways
Manage an on-premises data gateway
Manage high availability clusters and load balancing
Update an on-premises data gateway
Migrate, restore, or take over a gateway
Restart a gateway
Tenant level administration
Troubleshoot the on-premises data gateway
Monitor and optimize gateway performance
Reference
PowerShell support for gateway clusters
Resources
Previous monthly updates
 What is an on-premises data gateway?
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback on
this article, or the overall gateway docs experience, scroll to the bottom of the article.

The on-premises data gateway acts as a bridge, providing quick and secure data transfer between on-premises
data (data that is not in the cloud) and several Microsoft cloud services, including Power BI, PowerApps, Microsoft
Flow, Azure Analysis Services, and Logic Apps. By using a gateway, organizations can keep databases and other
data sources on their on-premises networks, yet securely use that on-premises data in cloud services.

How the gateway works

For detailed information on how the gateway works, see On-premises data gateway architecture.

Types of gateways
There are two different types of gateways, each for a different scenario:
On-premises data gateway – allows multiple users to connect to multiple on-premises data sources. You
can use an on-premises data gateway with all supported services, with a single gateway installation. This
gateway is well-suited to complex scenarios with multiple people accessing multiple data sources.
On-premises data gateway (personal mode) – allows one user to connect to sources, and can’t be
 shared with others. An on-premises data gateway (personal mode) can be used only with Power BI. This
gateway is well-suited to scenarios where you’re the only person who creates reports, and you don't need to
share any data sources with others.

Using a gateway
There are four main steps for using a gateway:
1. Download and install the gateway on a local computer.
2. Configure the gateway based on your firewall and other network requirements.
3. Add gateway admins who can also manage and administer other network requirements.
4. Troubleshoot the gateway in case of errors.

Next steps
Install the on-premises data gateway
 On-premises data gateway architecture
7/17/2019 • 4 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

It's possible for users in your organization to access on-premises data (to which they already have access
authorization), but before those users can connect to your on-premises data source, an on-premises data gateway
needs to be installed and configured. The gateway facilitates quick and secure behind-the-scenes communication
between a user in the cloud, to your on-premises data source, and then back to the cloud.
Installing and configuring a gateway is usually done by an administrator. It may require special knowledge of your
on-premises servers and in some cases may require Server Administrator permissions.
This article doesn’t provide step-by-step guidance on how to install and configure the gateway. For that, be sure to
see Install an-premises data gateway. This article is meant to provide you with an in-depth understanding of how
the gateway works.

How the gateway works

Let’s first look at what happens when a user interacts with an element connected to an on-premises data source.

NOTE
Depending on the cloud service, you will need to configure a data source for the gateway.

1. A query will be created by the cloud service, along with the encrypted credentials for the on-premises data
 source, and sent to the queue for the gateway to process.
2. The gateway cloud service will analyze the query and will push the request to the Azure Service Bus.
3. Azure Service Bus sends the pending requests to the on-premises data gateway.
4. The gateway gets the query, decrypts the credentials, and connects to the data source(s) with those credentials.
5. The gateway sends the query to the data source for execution.
6. The results are sent from the data source, back to the gateway, and then onto the cloud service. The service
then uses the results.
For queries returning large amounts of data in step 6 (like Power BI refreshes and AAS refreshes), data is
temporarily stored on disk (SSD recommended) on the gateway machine, until all data is received from the data
source. It is then sent back to the cloud service. This process is called spooling.

Authentication to on-premises data sources

A stored credential will be used to connect to on-premises data sources from the gateway. Regardless of the
individual user, the gateway uses the stored credential to connect. There may be exceptions, for example
DirectQuery and LiveConnect (for Analysis Services) in Power BI.

Sign in account
Users sign in with either a work or school account. This is your organization account. If you signed up for an Office
365 offering and didn’t supply your actual work email, it may look like [email protected]. Your
account, within a cloud service, is stored within a tenant in Azure Active Directory (AAD ). In most cases, your AAD
account’s UPN will match the email address.

Azure Active Directory

Microsoft cloud services use Azure Active Directory to take care of authenticating users. Azure Active Directory is
the tenant that contains usernames and security groups. Typically, the email address a user signs in with is the
same as the UPN of the account.
How do I tell what my UPN is?
You may not know what your UPN is, and you may not be a domain administrator. You can use the following
command from your workstation to find out the UPN for your account: whoami /upn .
The result will look similar to an email address, but this is the UPN that is on your local domain account.
Synchronize an on-premises Active Directory with Azure Active Directory
You want your local Active Directory accounts to match Azure Active Directory, because the UPN has to match
between the accounts.
The cloud services only know about accounts within Azure Active Directory. It doesn’t matter if you added an
account in your local Active Directory, if it doesn’t exist in AAD, it cannot be used. There are different ways that you
can match your local Active Directory accounts with Azure Active Directory.
You can add accounts manually to Azure Active Directory.
You can create an account on the Azure portal, or within the Microsoft 365 admin center, and the account
name matches the UPN of the local Active Directory account.
You can use the Azure AD Connect tool to synchronize local accounts to your Azure Active Directory tenant.
The Azure AD Connect tool provides options for directory synchronization and setting up authentication,
including password hash sync, pass-through authentication, and federation. If you are not a tenant admin or
a local domain administrator, you will need to contact your IT admin to get this configured.
Using Azure AD Connect ensures that the UPN will match between AAD and your local Active Directory. This will
help if you're using Analysis Services live connections with Power BI or single sign-on (SSO ) capabilities.

NOTE
Synchronizing accounts with the Azure AD Connect tool will create new accounts within your AAD tenant.

Next steps
On-premises data gateway FAQ
Azure Service Bus
Azure AD Connect
 On-premises data gateway FAQ
7/17/2019 • 5 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

General
Question: What is the actual Windows service called?
Answer: The gateway is called On-premises data gateway service in Services.
Question: What are the requirements for the gateway?
Answer: Take a look at the requirements section of the installation article.
Question: Do I need a gateway for cloud data sources like Azure SQL Database?
Answer: No. In general, the service will be able to connect to that data source without a gateway. However, for on-
premises data sources, or if the data sources reside behind a firewall, or requires a VPN, or are on virtual networks,
a data gateway may be needed.
Question: Are there any inbound connections to the gateway from the cloud?
Answer: No. The gateway uses outbound connections to Azure Service Bus.
Question: What if I block outbound connections? What do I need to open?
Answer: See Enable outbound Azure connections.
Question: Does the gateway have to be installed on the same machine as the data source?
Answer: No. The gateway will connect to the data source using the connection information that was provided.
Think of the gateway as a client application in this sense. It will just need to be able to connect to the server name
that was provided.
Question: Are there any permissions prerequisites to install gateways?
Answer: There are no restrictions for installing and registering a gateway, but every cloud service could have
restrictions on how gateways are used within their service based on licensing.
Question: What is the latency for running queries to a data source from the gateway? What is the best
architecture?
Answer: We recommend that you have the gateway as close to the data source as possible to avoid network
latency. If you can install the gateway on the actual data source, it will minimize the latency introduced. Consider
the data centers as well. For example, if your service is making use of the West US data center, and you have SQL
Server hosted in an Azure VM, you will want to have the Azure VM in West US as well. This will minimize latency
and avoid egress charges on the Azure VM.
Question: Are there any requirements for network bandwidth?
Answer: We recommend that you have good throughput for your network connection. Every environment is
different and this is also dependent on the amount of data being sent. Using ExpressRoute could help to guarantee
a level of throughput between on-premises and the Azure data centers.
You can use the 3rd party Azure Speed Test app to help gauge what your throughput is.
Question: Can the gateway Windows service run with an Azure Active Directory account?
Answer: No. The Windows service needs to have a valid Windows account. By default it will run with the Service
SID NT SERVICE\PBIEgwService.
Question: How are results sent back to the cloud?
Answer: This is done by way of the Azure Service Bus. For more information, see on-premises data gateway
architecture.
Question: Where are my credentials stored?
Answer: The credentials you enter for a data source are stored encrypted in the gateway cloud service. The
credentials are decrypted at the gateway on-premises.
Question: Can I place the gateway in a perimeter network (also known as DMZ, demilitarized zone, and screened
subnet)?
Answer: The gateway requires connectivity to the data source. If the data source is not accessible in your
perimeter network, the gateway may not be able to connect to it. For example, your SQL Server may not be in
your perimeter network. And, you cannot connect to your SQL Server from the perimeter network. If you placed
the gateway in your perimeter network, it would not be able to reach the SQL Server.
Question: Is it possible to force the gateway to use HTTPS traffic with Azure Service Bus instead of TCP?
Answer: Yes. For more information, see Force HTTPS communication with Azure Service Bus. Turning on this
feature has very little impact on performance.
Question: Do I need to whitelist the Azure Datacenter IP list? Where do I get the list?
Answer: If you are blocking outbound IP traffic, you may need to whitelist the Azure Datacenter IP list. Currently,
the gateway will communicate with Azure Service Bus using the IP address in addition to the fully qualified
domain name. The Azure Datacenter IP list is updated weekly. For more information, see Enable outbound Azure
connections.
Question: Are the on-premises data gateway and the Data Management Gateway (used by Azure Machine
Learning Studio and Azure Data Factory) the same thing?
Answer: No, they are two different products. To get more information about the Data Management Gateway (now
called Self-hosted Integration Runtime), see Create and configure a self-hosted integration runtime.
Question: Can the person who sets up that gateway in the Azure Portal be different from the one who installs the
gateway?
Answer: Yes. You'll have to use PowerShell to add other owners to the same gateway and these users could create
the gateway on the portal. However, the tenant under which they connect to Azure Portal and the gateway should
be the same.

High Availability/Disaster Recovery

Question: Are there any plans for enabling high availability scenarios with the gateway?
Answer: High availability clusters of on-premises data gateways help with avoiding a single point of failure. Cloud
services like PowerApps or Power BI use the primary node by default, but falls back to the secondary in case the
primary is unavailable.
Question: What options are available for disaster recovery?
Answer: You can use the recovery key to restore or move a gateway. When you install the gateway, supply the
recovery key.
Question: What is the benefit of the recovery key?
Answer: It provides a way to migrate, recover, take over, or add a new gateway to the cluster.

Troubleshooting
Question: Where are the gateway logs located?
Answer: See Troubleshooting tools.
Question: How can I see what queries are being sent to the on-premises data source?
Answer: You can enable query tracing by turning on Additional logging. This will include the queries being sent.
Remember to turn query tracing back off when done troubleshooting. Having query tracing enabled will cause the
logs to be larger.
You can also look at tools your data source has for tracing queries. For example, for SQL Server and Analysis
Services you can use Extended Events or SQL Profiler.

Administration
Question: Can I have more than one admin for a gateway?
Answer: Yes. When you manage a gateway, you can go to the administrator’s tab to add additional admins. You
can also have security groups as admins.
Question: Does the gateway admin need to be an admin on the machine where the gateway is installed?
Answer: No. The gateway admin is used to manage the gateway from within the service.

Next steps
Troubleshoot the on-premises data gateway
 Install an on-premises data gateway
8/1/2019 • 4 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

An on-premises data gateway is software that you install in an on-premises network. It facilitates access to data in
that network. As we explained in the overview, you can install a gateway in standard mode (recommended) or
personal mode (Power BI only). In standard mode, you can install a stand-alone gateway or add a gateway to a
cluster, which we recommend for high availability. In this article, we show you how to install a standard gateway
and then add another gateway to create a cluster.

Requirements
Minimum requirements:
.NET Framework 4.6
64-bit version of Windows 7 / Windows Server 2008 R2 (or later)
Recommended:
8-core CPU
8 GB of memory
64-bit version of Windows Server 2012 R2 (or later)
Solid state drive (SSD ) based storage for spooling
Related considerations:
The user installing the gateway is required to be the admin of the gateway.
The gateway can't be installed on a domain controller.
If you're planning to use Windows authentication, make sure you install the gateway on a computer that's a
member of the same Active Directory environment as the data sources.
You shouldn't install a gateway on a computer, like a laptop, that might be turned off, asleep, or disconnected
from the internet. The gateway can't run under any of those circumstances. Also, gateway performance might
suffer over a wireless network.
You can install up to two on-premises data gateways on a single computer, one running in each mode
(personal and standard). You can't have more than one gateway running in the same mode on the same
computer.

Download and install a gateway

The gateway runs on the computer that you install it on, so be sure to install it on a computer that's always on. For
better performance and reliability, we recommend that the computer is on a wired network rather than a wireless
one.
1. Download the on-premises data gateway.
2. In the installer, select Next.

3. Select On-premises data gateway (recommended) > Next.

NOTE
The On-premises data gateway (personal mode) option can be used only with Power BI. For more information
on installation, management, and use of personal gateways, see Use personal gateways in Power BI.

4. Select Next.
5. Keep the default installation path, accept the terms, and then select Install.

6. Enter the email address for your Office 356 organization account, and then select Sign in.
 NOTE
You need to sign in with either a work account or a school account. This account is an organization account. If you
signed up for an Office 365 offering and didn't supply your work email address, the address might look like
[email protected]. Your account is stored within a tenant in Azure Active Directory (Azure AD). In
most cases, your Azure AD account’s User Principal Name (UPN) will match the email address.

The gateway is associated with your Office 356 organization account, and you manage gateways from
within the associated service. You're now signed in to your account.
7. Select Register a new gateway on this computer > Next.

8. Enter a name for the gateway (it must be unique across the tenant) and a recovery key. You'll need this key
if you ever want to recover or move your gateway. Select Configure.
 Notice the Add to an existing gateway cluster option. We'll use this option in the next section of this
article.
Also note that you can change the region that connects the gateway to cloud services. The region should be
changed to the region of your Power BI tenant or your Office 356 tenant, or the closest Azure region to
you. For more information, see Set the data center region.
9. Review the information in the final window. Notice that the gateway is available for Power BI, PowerApps,
and Microsoft Flow, because in this example we use the same account for all three. Select Close.
Now that you've installed a gateway, you can add another gateway to create a cluster.

Add another gateway to create a cluster

A cluster allows gateway admins to avoid having a single point of failure for on-premises data access. If the
primary gateway is unavailable, data requests are routed to the second gateway that you add, and so on. You can
install only one standard gateway on a computer, so you have to install the second gateway for the cluster on a
different computer. This makes sense because you want redundancy in the cluster.
To create high availability gateway clusters, you need the November 2017 or later update to on-premises data
gateway.
1. Download the gateway to a different computer and install it.
2. After you sign in to your Office 356 organization account, register the gateway. Select Add to an existing
cluster. Under Available gateway clusters, select the first gateway you installed (the primary gateway),
and enter the recover key for that gateway. Select Configure.
Next steps
Configure on-premises data gateways
Manage an on-premises data gateway
Monitor and optimize gateway performance
 Use the on-premises data gateway app
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

To open the on-premises data gateway app:

1. On the machine where the gateway is running, enter gateway in Windows search.
2. Select the on-premises data gateway app.
Some of the on-premises data gateway app features can only be used once you've signed on to your Office 356
account. For example, under the Service Settings tab, you can restart the gateway without signing on, but you
can't change the service account of your gateway without signing on.

On-premises data gateway app features

Once you've signed on to your Office 356 account, you have access to the following features in the on-premises
data gateway app.

TAB SERVICE DESCRIPTION

Status Status of the gateway cluster Indicates whether your gateway is

online, the version number of the
gateway, and a list of any apps
currently associated with the gateway.

Service Settings Restart the gateway Provides a way of restarting the

gateway whenever a restart is needed.

Service Settings Gateway service account By default, the gateway is configured to

use NT SERVICE\PBIEgwService for the
Windows service sign in credential. You
can change the service account to a
domain user account within your Active
Directory domain. Or, you can use a
managed service account to avoid
having to change the password.
 TAB SERVICE DESCRIPTION

Diagnostics Additional logging Turning this feature on provides

additional verbose information in the
log file, including duration information.
This information can be useful in
figuring out why some responses
through the gateway are slow. Enabling
this feature could increase the log size
significantly depending on gateway
usage. So, we recommend that you
don't leave this setting enabled long
term.

Diagnostics Gateway logs Provides a copy of all of the gateway

logs in a single file in .zip format.

Diagnostics Network ports test Checks if the gateway has access to all
required ports.

Network Network status Indicates whether the gateway can

reach outside your network. The
network status is displayed as either
Connected or Disconnected.

Network HTTPS mode Forces the gateway to communicate

with Azure Service Bus by using HTTPS
instead of TCP when turned on.

Connectors Custom data connectors Enables you to connect to and access

data from Power BI using custom data
connectors that you develop.

Next steps
Troubleshoot the on-premises data gateway
 Configure proxy settings for the on-premises data
gateway
7/16/2019 • 2 minutes to read • Edit Online

Your work environment might require that you go through a proxy to access the internet. This could prevent the
Microsoft on-premises data gateway from connecting to the service.
The following post on superuser.com discusses how you can try to determine if you have a proxy on your network:
How do I know what proxy server I'm using? (SuperUser.com) .
Although most gateway configuration settings can be changed using the on-premises data gateway app, proxy
information is configured within a .NET configuration file. The location and file names are different, depending on
the gateway you're using.
There are two main configuration files that are involved with the gateway in which proxy settings can be edited.
The first is for the configuration screens that actually configure the gateway. If you're having issues configuring the
gateway, look at the following file: C:\Program Files\On-premises data
gateway\enterprisegatewayconfigurator.exe.config.
The second is for the actual Windows service that interacts with the cloud service using the gateway. This file
handles the requests: C:\Program Files\On-premises data
gateway\Microsoft.PowerBI.EnterpriseGateway.exe.config.
If you're going to make changes to the proxy configuration, these files must be edited so that proxy configurations
are exactly the same in both files.

Configure proxy settings

The following sample shows the default proxy configuration found in both of the two main configuration files.

<system.net>
<defaultProxy useDefaultCredentials="true" />
</system.net>

The default configuration works with Windows authentication. If your proxy uses another form of authentication,
you'll need to change the settings. If you aren't sure, you should contact your network administrator.
We don't recommend basic proxy authentication. Using basic proxy authentication may cause proxy authentication
errors that result in the gateway not being properly configured. Use a stronger proxy authentication mechanism to
resolve.
In addition to using default credentials, you can add a <proxy> element to define proxy server settings in more
detail. For example, you can specify that your on-premises data gateway should always use the proxy, even for
local resources, by setting the bypassonlocal parameter to false. This can help in troubleshooting situations, if you
want to track all HTTPS requests originating from a gateway in the proxy log files. The following sample
configuration specifies that all requests must go through a specific proxy with the IP address 192.168.1.10.
 <system.net>
<defaultProxy useDefaultCredentials="true">
<proxy
autoDetect="false"
proxyaddress="http://192.168.1.10:3128"
bypassonlocal="false"
usesystemdefault="true"
/>
</defaultProxy>
</system.net>

Additionally, for the gateway to connect to cloud data sources through a proxy, update the following file:
C:\Program Files\On-premises data gateway\Microsoft.Mashup.Container.NetFX45.exe.config.
In the file, expand the <configurations> section to include the contents below, and update the proxyaddress
attribute with your proxy information. The following example routes all cloud requests through a specific proxy
with the IP address 192.168.1.10.

<configuration>
<system.net>
<defaultProxy useDefaultCredentials="true" enabled="true">
<proxy proxyaddress="http://192.168.1.10:3128" bypassonlocal="true" />
</defaultProxy>
</system.net>
</configuration>

To learn more about the configuration of the proxy elements for .NET configuration files, see defaultProxy Element
(Network Settings).

Change the gateway service account to a domain user

As explained earlier, when you configure the proxy settings to use default credentials, you might encounter
authentication issues with your proxy. This is because the default service account is the Service SID, and not an
authenticated domain user. You can change the service account of the gateway to allow proper authentication with
your proxy. For more information about how to change the gateway service account, see Change the on-premises
data gateway service account.

NOTE
We recommend that you use a managed service account to avoid having to reset passwords. Learn how to create a
managed service account within Active Directory.

Next steps
Firewall information
 Change the on-premises data gateway service
account
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

The on-premises data gateway is configured to use NT SERVICE\PBIEgwService for the Windows service sign in
credential. By default, it has the right of Log on as a service, in the context of the machine that you're installing the
gateway on. The account isn't the same account used to connect to on-premises data sources. The account is also
not the work or school account that you sign in to cloud services with.

Change the service account

To change the Windows service account for the on-premises data gateway:
1. Open the on-premises data gateway app, select Service settings, and then select Change account.

The default account for this service is NT SERVICE\PBIEgwService. You'll want to change this to a domain
 user account within your Active Directory domain. Or, you'll want to use a managed service account to
avoid having to change the password.
2. You'll need the recovery key to change the service account. Select the Change Account button.

3. Provide the service account and password and select the Configure button.
4. Provide your sign in account and select Sign in.
5. On the next screens select "Migrate, restore or takeover an existing gateway" and follow the process for
restoring your gateway.
6. Once the restore process is complete, the new gateway will use the domain account.

Next steps
Set the data center region
 Set the data center region for the on-premises data
gateway
7/23/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

During gateway installation, you can set the data center region used by the gateway. By default, the data center
region is the region of your Power BI tenant or your Office 365 tenant if you have registered for either of these
services. If not, it may be the closest Azure region to you.

Change the data center region

If you want to change the data center region after your gateway is installed, you can:
Restore the on-premises data gateway on the current gateway machine.
Migrate or take over the on-premises data gateway on a different machine.
Current data center region
To find the current data center region you're in after the gateway is installed:
1. Open the on-premises data gateway app and sign in to your account.
2. In the Status tab, your data region is listed under Logic Apps, Azure Analysis Services.
For more information about setting the data region for your resources, watch this video.

Next steps
Adjust communications settings
 Adjust communication settings for the on-premises
data gateway
7/17/2019 • 5 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

This article describes several communication settings associated with the on-premises data gateway, and how to
adjust them.

Enable outbound Azure connections

The Microsoft on-premises data gateway relies on Azure Service Bus for cloud connectivity, and correspondingly
establishes outbound connections to its associated Azure region. By default, this is the region of your Power BI
tenant or your Office 356 tenant if you have registered for either of these services. If not, it may be the closest
Azure region to you.
If a firewall is blocking outbound connections, you must configure the firewall to allow outbound connections from
the on-premises data gateway to its associated Azure region.

Ports
The Microsoft on-premises data gateway communicates on outbound ports: TCP 443, 5671, 5672, 9350 through
9354. The gateway doesn't require inbound ports.
We recommend that you whitelist the IP addresses, for your data region, in your firewall. You can download the
Microsoft Azure Datacenter IP list, which is updated weekly. Alternatively you can obtain the list of required ports
by performing the Network ports test in the on-premises data gateway app.
The gateway communicates with Service Bus by using the IP address, along with the fully qualified domain name
(FQDN ). If you're forcing the gateway to communicate by using HTTPS, it will strictly use FQDN only, and no
communication happens by using IP addresses.

NOTE
The IP addresses listed in the Azure Datacenter IP list are in CIDR notation. For example, 10.0.0.0/24 doesn't mean 10.0.0.0
through 10.0.0.24. Learn more about CIDR notation.

Here's a list of FQDNs used by the gateway:

DOMAIN NAMES OUTBOUND PORTS DESCRIPTION

*.download.microsoft.com 80 Used to download the installer. This is

also used by the on-premises data
gateway app to check for version and
gateway region.
 DOMAIN NAMES OUTBOUND PORTS DESCRIPTION

*.powerbi.com 443 Used for identifying the relevant Power

BI cluster.

*.analysis.windows.net 443 Used for identifying the relevant Power

BI cluster.

*.login.windows.net, login.live.com, 443 Used for authenticating the on-

aadcdn.msauth.net premises data gateway app
(AAD/OAuth2).

*.servicebus.windows.net 5671-5672 Used for Advanced Message Queuing

Protocol (AMQP).

*.servicebus.windows.net 443, 9350-9354 Listens on Service Bus Relay over TCP

(requires 443 for Access Control token
acquisition).

*.frontend.clouddatahub.net 443 Deprecated - Not required. Will be

removed from the public
documentation as well.

*.core.windows.net 443 Used by data flows in Power BI to write

data to Azure data lake.

login.microsoftonline.com 443 Used for authenticating the on-

premises data gateway app
(AAD/OAuth2).

*.msftncsi.com 443 Used to test internet connectivity if the

gateway is unreachable by the Power BI
service.

*.microsoftonline-p.com 443 Used for authenticating the on-

premises data gateway app
(AAD/OAuth2).

dc.services.visualstudio.com 443 Used by AppInsights to collect

telemetry.

NOTE
Once the gateway is installed and registered, the only required ports/IPs are the ones needed by the Azure service bus
(servicebus.windows.net in the table above). You can obtain the list of required ports by performing the Network ports test in
the on-premises data gateway app. Additionally you could also force the gateway to communicate using HTTPS.

Network ports test

To test if the gateway has access to all the required ports:
1. On the machine where the gateway is running, enter gateway in Windows search, and then select the On-
premises data gateway app.
2. Select the Diagnostics tab, and then select Start new test under Network ports test.
When running the network ports test, your gateway retrieves a list of ports and servers from Azure Service Bus
and then attempts to connect to all the servers and ports. When the Start new test link reappears, the network
ports test has finished running. The results of the test are either Completed (Succeeded) or Completed (Failed, see
last test results). If the test succeeded, then your gateway successfully connected to all the required ports. If the test
failed, then your network environment might be blocking these required ports and servers.
To view the results of the last completed test, select the Open last completed test results link. The test results open
in Windows’ default text editor.
The test results list all the servers, ports, and IP addresses that are required by your gateway. If the test results
display Closed for any ports as shown below, ensure that your network environment is not blocking the
connection. You may need to contact your network administrator to open the required ports.
Force HTTPS communication with Azure Service Bus
You can force the gateway to communicate with Azure Service Bus by using HTTPS instead of direct TCP.

NOTE
Starting with the June 2019 release, new installs (not updates) default to HTTPS instead of TCP, based on recommendations
from Azure Service Bus.

You can use the on-premises data gateway app to force the gateway to adopt this behavior. In the on-premises
data gateway app, select Network, and then switch the HTTPS mode to On.
After you make this change, when you select Apply (a button that only appears when you make a change), the
gateway Windows service restarts automatically so the change can take effect.
For future reference, to restart the gateway Windows service from the on-premises data gateway app, see Restart
a gateway.

NOTE
If the gateway can't communicate by using TCP, it falls back automatically to HTTPS. The selection in the on-premises data
gateway app always reflects the current value.

TLS 1.2 for gateway traffic

By default, the Microsoft on-premises data gateway uses Transport Layer Security (TLS ) 1.2 to communicate with
the Microsoft Power BI service. To ensure all gateway traffic uses TLS 1.2, you might have to add or modify the
following registry keys on the machine running the gateway service:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]"SchUseStrongCrypto"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319]"SchUseStrongCrypto"=dword:0000000
1

NOTE
Adding or modifying these registry keys applies the change to all .NET applications. For information about registry changes
that affect TLS for other applications, see Transport Layer Security (TLS) registry settings.
Next steps
Configure the gateway log file
 Configure log files for the on-premises data gateway
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

There are three categories of gateway service logs: information, error, and network. This categorization provides a
better troubleshooting experience that allows you to focus on a specific area, depending on the error or issue. You
can see the three categories, GatewayInfo.log , GatewayErrors.log , and GatewayNetwork.log , in the following
snippet from the gateway configuration file Microsoft.PowerBI.EnterpriseGateway.exe.config.

<system.diagnostics>
<trace autoflush="true" indentsize="4">
<listeners>
<remove name="Default" />
<add name="ApplicationFileTraceListener"

type="Microsoft.PowerBI.DataMovement.Pipeline.Common.Diagnostics.RotatableFilesManagerTraceListener,
Microsoft.PowerBI.DataMovement.Pipeline.Common"
initializeData="%LOCALAPPDATA%\Microsoft\On-premises data
gateway\,GatewayInfo.log,GatewayErrors.log,GatewayNetwork.log,20,50" />
</listeners>
</trace>
</system.diagnostics>

By default, the gateway configuration file is located at \Program Files\On-premises data gateway. To set the
number of log files to retain, change the first number. You can also configure the size of the log file by changing the
second number.
In this example, 20 log files of 50 MB each will be retained:
GatewayInfo.log,GatewayErrors.log,GatewayNetwork.log,20,50

Next steps
For information on how to export gateway logs for troubleshooting, see Troubleshooting tools.
 Manage an on-premises data gateway
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

After you install an on-premises data gateway, you manage it based on your requirements. Every service might
integrate gateways differently, so the management options differ depending on the service. While you can manage
gateways from any of these services, the articles in this section refer to the "Manage gateways" page in Power BI.

NOTE
Manage gateways will not show up until you're the admin of at least one gateway. This can happen either by being added
as an admin or you installing and configuring a gateway.

Manage gateway admins

When you install a gateway, you are by default an admin of that gateway. You can then add additional users or
security groups as admins using the Administrators tab for the gateway. You can also remove administrators
using this option.
 NOTE
Groups without an email can't be added.

Remove or delete an on-premises data gateway

You can remove (Power BI) or delete (PowerApps, Microsoft Flow ) an on-premises data gateway if you're no
longer using it.
However, be aware that removing a gateway in Power BI deletes all the data sources under it. Deleting the Power
BI data sources in turn breaks any Power BI dashboards and reports that rely on those data sources.

NOTE
If you remove or delete a gateway cluster in any of the cloud services, you won't be able to restore it. Also, when you
remove or delete a gateway cluster, the gateway is not uninstalled from the gateway machine. You'll have to manually
uninstall it from each gateway machine in the cluster.

For example, to remove a gateway in the Power BI service:

1. In the upper-right corner of the Power BI service, select the gear icon > Manage gateways.
2. Select the gateway > Remove
Next steps
Manage high availability clusters and load balancing
Tenant level administration
 Manage on-premises data gateway high availability
clusters and load balancing
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

You can use a gateway cluster to avoid single points of failure, and to load balance traffic across gateways in a
cluster.

High availability clusters for on-premises data gateway

You can create high availability clusters of on-premises data gateway installations to ensure your organization can
access on-premises data resources using any cloud services like Power BI, PowerApps, and others. Such clusters
allow gateway administrators to group gateways to avoid single points of failure in accessing on-premises data
resources. The gateway cloud service always uses the primary gateway in the cluster, unless it’s not available. In
that case, the service switches to the next gateway in the cluster, and so on.
Manage a gateway cluster
Once you create a cluster of two or more gateways, all gateway management operations, such as granting
administrative permissions to a gateway or adding data sources/connections, apply to all gateways that are part of
the cluster.
For example, in Manage gateways in Power BI, administrators see the list of registered clusters or individual
gateways, but do not see the individual gateway instances that are members of the cluster.
All requests are routed to the primary instance of a given gateway cluster. If the primary gateway instance is not
online, the request is routed to another gateway instance in the cluster.

Load balance across gateways in a cluster

You can choose to allow traffic to be distributed evenly across gateways in a cluster. Currently, the selection of a
gateway during load balancing is random.

For example, to provide load balancing from the Power BI service, first select the gear icon in the upper-right
corner, then select Manage gateways. Then enable the option to "Distribute requests across all active gateways
in this cluster."
Next steps
PowerShell support for gateway clusters
 Update an on-premises data gateway
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback on
this article, or the overall gateway docs experience, scroll to the bottom of the article.

We aim at releasing an update every month for on-premises data gateways. Each of these updates includes new
features along with the latest mashup update.

NOTE
If you're running a gateway cluster, we recommend that you update all nodes in the cluster at the same time.

Update the gateway

To update an on-premises data gateway:
1. Download the latest gateway and run the installation. If the version you're trying to install is the same or
older than the version on the machine, then you'll receive one of the respective error messages.
2. If you install a more recent version, you'll be prompted to update. Select the Update button to begin
updating.

3. Once the installation is completed, select the Sign in button.

The on-premises data gateway update is now complete.
Next steps
Monitor and optimize gateway performance
 Migrate, restore, or take over an on-premises data
gateway
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

Run the gateway installer on a computer where you want to migrate, restore, or take over the gateway.
If you're restoring the gateway on the same computer as the original gateway was installed on, you must first
uninstall the gateway on that computer before restoring the gateway.

NOTE
If you remove or delete a gateway cluster in any of the cloud services, you will not be able to restore it.

1. Download the gateway and install it. For more information, see Install an on-premises data gateway.
2. After you've signed in to your Office 356 account, register the gateway. Select Migrate, restore, or take
over an existing gateway > Next.

3. Select from the available clusters and gateways, and enter the recover key for the selected gateway. The
recovery key is the one you created and safely stored when you originally installed the gateway (see step 8
in Install an on-premises data gateway).
4. Select Configure.
Once the configuration finishes, the migrate, restore, or takeover process is complete.

Next steps
Troubleshoot the on-premises data gateway
 Restart an on-premises gateway
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

The on-premises data gateway service can be restarted using multiple methods.
1. In the on-premises data gateway app, select the Service Settings tab, then select Restart now.

2. You can also restart the service from the services application. Find the on-premises data gateway service
and restart.

3. To restart the gateway from an admin command prompt, use the following commands:
 net stop PBIEgwService

net start PBIEgwService

Next steps
Tenant level administration
 Tenant level administration for the on-premises data
gateway
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

You can use the Power Platform Admin center to get visibility into all on-premises data gateways in a tenant. To do
so, sign in as a tenant admin and select the Data Gateways option.

NOTE
Only users who are part of the Azure AD tenant Global administrator role (which includes Office 365 Global admins) will see
the Data Gateways option.

The Gateways page lists all on-premises data gateway clusters installed on the tenant. In addition, you can review
the following information about these clusters:
Gateway Cluster Name: The name of the gateway cluster.
Contact Info: Admin contact information for the gateway cluster.
Administrators: The list of gateway administrators.
Gateways: The number of gateway members in the gateway cluster.

Display gateway members

Select the Open in new window icon ( ) next to the gateway cluster name to see the gateway members, device
name, and version in each gateway cluster.
Manage gateway admins
Select the People icon ( ) next to the gateway cluster name to see the list of gateway admins. Add or remove
gateway admins in the Manage Administrators page.
For personal gateways, this would show the owner of the personal gateway and cannot be changed due to the
security scope of personal gateways.

Search
Use Search to find gateway clusters and see their details. You can search for gateway cluster names and contact
info, but not administrators.
Next steps
Manage an on-premises data gateway
Manage high availability clusters and load balancing
 Troubleshoot the on-premises data gateway
7/17/2019 • 4 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

This article discusses some common issues when using the on-premises data gateway.

NOTE
If you encounter an issue that is not listed below, you can create a support ticket for the particular cloud service that's
running the gateway.

Update to the latest version

Issues can occur when the gateway version is out of date. It's a good general practice to make sure you're using
the latest version. If you haven't updated the gateway for a month, or longer, you might want to consider installing
the latest version of the gateway. Then see if you can reproduce the issue.
Inconsistent versions between gateway members in a cluster
Keep the versions of the gateway members in a cluster in sync. Having all the same version in a cluster will help
avoid unexpected refresh failures. These refresh failures might occur because the gateway member that a specific
query is routed to may not be capable of executing it due to a lower version.

Troubleshoot common installation issues

Here are a few common installation issues and the resolutions that have helped a number of customers.
Error: Failed to add user to group. (-2147463168 PBIEgwService Performance Log Users )
You might receive this error if you're trying to install the gateway on a domain controller. Deploying on a domain
controller isn't supported. You'll need to deploy the gateway on a machine that isn't a domain controller.
Out of date anti-virus
You might encounter installation failures if the anti-virus software on the installation machine is out of date. You
can either update the anti-virus installation, or disable the anti-virus only for the duration of the gateway
installation. Once the installation is complete, then re-enable the anti-virus.
Same or older gateway version
You might come across the following error if you try to install the same version or a previous version of the
gateway compared to the one that you already have.
Troubleshoot configuration
Firewall or proxy
To test if the gateway has access to all the required ports, run the network ports test. The results of the test are
either Completed (Succeeded) or Completed (Failed, see last test results). If the test succeeded, then your gateway
successfully connected to all the required ports. If the test failed, then your network environment might be
blocking these required ports and servers.
For information on providing proxy information for your gateway, see Configure proxy settings for the on-
premises data gateway.
A firewall might also be blocking the connections that the Azure Service Bus makes to the Azure data centers. If
that's the case, you'll want to whitelist (unblock) the IP addresses for your region for those data centers. You can
get a list of Azure IP addresses here. To find the current data center region you're in, see Set the data center
region.
Authentication to proxy server
Your proxy may require authentication from a domain user account. By default, the gateway uses a Service SID for
the windows service sign in user. Changing the sign in user to a domain user can help with this. For more
information, see Change the gateway service account to a domain user.
Your proxy only allows ports 80 and 443 traffic
Some proxies restrict traffic to only ports 80 and 443. By default, communication to Azure Service Bus occurs on
ports other than 443.
You can force the gateway to communicate with Azure Service Bus using HTTPS instead of direct TCP.
Common errors
Error: Failed to create a gateway. Try again
This error could be due to proxy configuration issues. The gateway log provides additional details for
troubleshooting. For more information, see Configure proxy settings for the on-premises data gateway.
Error: Power BI service reported local gateway as unreachable. Restart the gateway and try again
At the end of configuration, the Power BI service is called again to validate the gateway. The Power BI service
doesn't report the gateway as live. Restarting the windows service may allow the communication to be successful.
You can collect and review the logs, as described in the following section, to get more details.

Troubleshooting tools
Collect logs from the on-premises data gateway app
There are several logs you can collect for the gateway, and you should always start with the logs. The simplest way
to collect logs after installing the gateway is through the on-premises data gateway app. In the on-premises data
gateway app, select Diagnostics and then select the Export logs link, as shown in the following image.

This file is saved to the ODGLogs folder on your Windows desktop in .zip format.
Event Logs
The on-premises data gateway service event logs are present under Application and Services Logs.
Next steps
On-premises data gateway FAQ
 Monitor and optimize on-premises data gateway
performance
8/1/2019 • 9 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

Monitor performance
https://www.youtube.com/embed/IJ_DJ30VNk4?showinfo=0
Performance counters
There are a number of performance counters that you can use to gauge the activities for the gateway. It can be
helpful to understand these counters, especially if you have a large load of activity and need to make a new
gateway. These counters don't reflect how long something takes.
You can access these counters through the Windows Performance Monitor tool.

There are general groupings of these counters.

COUNTER TYPE DESCRIPTION

ADO.NET This counter type is used for any DirectQuery connection.

ADOMD This counter type is used for SQL Server 2014 Analysis
Services and earlier.

OLEDB Certain data sources use this counter type. Examples include
SAP HANA and SQL Server 2016 Analysis Services or later.

Mashup This counter type includes any imported data source. If you're
scheduling refresh or doing an on-demand refresh, it goes
through the Mashup Engine.
Here's a list of the available performance counters.

COUNTER DESCRIPTION

# of ADO.NET open connection executed / sec Number of ADO.NET open connection actions executed per
second (succeeded or failed).

# of ADO.NET open connection failed / sec Number of ADO.NET open connections actions failed per
second.

# of ADO.NET queries executed / sec Number of ADO.NET queries executed per second (succeeded
or failed).

# of ADO.NET queries failed / sec Number of ADO.NET failed queries executed per second.

# of ADOMD open connection executed / sec Number of ADOMD open connection actions executed per
second (succeeded or failed).

# of ADOMD open connection failed / sec Number of ADOMD open connection actions failed per
second.

# of ADOMD queries executed / sec Number of ADOMD queries executed per second (succeeded
or failed).

# of ADOMD queries failed / sec Number of ADOMD failed queries executed per second.

# of all open connection executed / sec Number of open connection actions executed per second
(succeeded or failed).

# of all open connection failed / sec Number of failed open connection actions executed per
second.

# of all queries executed / sec Number of queries executed per second (succeeded or failed).

# of items in the ADO.NET connection pool Number of items in the ADO.NET connection pool.

# of items in the OLEDB connection pool Number of items in the OLEDB connection pool.

# of items in the Service Bus pool Number of items in the Azure Service Bus pool.

# of Mashup open connections executed / sec Number of Mashup open connection actions executed per
second (succeeded or failed).

# of Mashup open connections failed / sec Number of Mashup open connection actions failed per
second.

# of Mashup queries executed / sec Number of Mashup queries executed per second (succeeded
or failed).

# of Mashup queries failed / sec Number of Mashup failed queries executed per second.

# of OLEDB multiple result set queries failed / sec Number of multiple result sets of OLEDB failed queries
executed per second.
 COUNTER DESCRIPTION

# of OLEDB multiple result sets of queries executed / sec Number of OLEDB multiple result sets of queries executed per
second (succeeded or failed).

# of OLEDB open connection executed / sec Number of OLEDB open connection actions executed per
second (succeeded or failed).

# of OLEDB open connection failed / sec Number of OLEDB open connection actions failed per second.

# of OLEDB queries executed / sec Number of OLEDB multiple result sets of queries executed per
second (succeeded or failed).

# of OLEDB queries failed / sec Number of OLEDB multiple result sets of failed queries
executed per second.

# of OLEDB single result set queries executed / sec Number of OLEDB single result set queries executed per
second (succeeded or failed).

# of queries failed / sec Number of failed queries executed per second.

# of single result set OLEDB queries failed / sec Number of single result set OLEDB failed queries executed per
second.

Slow-performing queries
Long-running queries might require additional modification on your data source or further optimization of the
query itself. This could be either for direct database queries, like Power BI DirectQuery, PowerApps, or Azure Logic
Apps, or for Power BI refreshes.
By default, the gateway performs basic logging. If you're investigating slow -performing queries and need more
information about query connection details, you can temporarily enable Additional logging to gather additional
log information. To do this, in the on-premises data gateway app select Diagnostics > Additional logging.
Enabling this setting likely will increase the log size significantly, based on gateway usage. We recommend that
after you finish reviewing the logs that you disable additional logging. We don't recommend leaving this setting
enabled during normal gateway usage.

Gateway performance monitoring (public preview)

To monitor performance, gateway admins have traditionally depended on manually monitoring performance
counters through the Windows Performance Monitor tool. We now offer additional query logging and a Gateway
Performance PBI template file to visualize the results. This feature provides new insights into gateway usage. You
can use it to troubleshoot slow -performing queries.

NOTE
This feature is currently available only for the on-premises data gateway in the standard mode. It's not available for the
personal mode.

Enable performance logging

To enable this feature, make the following changes to the
Microsoft.PowerBI.DataMovement.Pipeline.GatewayCore.dll.config file in the "\Program Files\On-premises data
gateway" folder.
1. Update QueryExecutionReportOn to True to enable additional logging for queries executed using the
gateway. Enabling this option creates both the Query Execution Report and the Query Execution
Aggregation Report files.
 <setting name="QueryExecutionReportOn" serializeAs="String">
<value>True</value>
</setting>

2. Update SystemCounterReportOn to True to enable additional logging for memory and CPU system
counters. Enabling this option creates the System Counter Aggregation Report file.

<setting name="SystemCounterReportOn" serializeAs="String">

<value>True</value>
</setting>

3. There are other values in the config file that you can update as needed:
ReportFilePath: Determines the path where the three log files are stored. By default, this path is either
"\Users\PBIEgwService\AppData\Local\Microsoft\On-premises data gateway\Report" or
"Windows\ServiceProfiles\PBIEgwService\AppData\Local\Microsoft\On-premises data
gateway\Report." The path depends on the OS version. If you use a service account for the gateway
other than PBIEgwService, replace this part of the path with the service account name.
ReportFileCount: Determines the number of log files of each kind to retain. The default value is 10.
ReportFileSizeInBytes: Determines the size of the file to maintain. The default value is 104,857,600.
QuerExecutionAggregationTimeInMinutes: Determines the number of minutes for which the query
execution information is aggregated. The default value is 5.
SystemCounterAggregationTimeInMinutes: Determines the number of minutes for which the
system counter is aggregated. The default value is 5.
4. After you make the changes to the config file, restart the gateway for these config values to take effect. You
now see the report files being generated in the location that you specified for ReportFilePath.

NOTE
It can take up to 10 minutes plus the amount of time set for QuerExecutionAggregationTimeInMinutes in the
config file until files start to show up in the folder.

Understand performance logs

When you turn this feature on, three new log files are created:
The Query Execution Report
The Query Execution Aggregation Report
The System Counter Aggregation Report
The Query Execution Report contains detailed query execution information. The following attributes are captured.

ATTRIBUTE DESCRIPTION

GatewayObjectId Unique identifier for the gateway.

RequestId Unique identifier for a gateway request. It could be the same

for multiple queries.

DataSource Contains both the data source type and data source.

QueryTrackingId Unique identifier for a query.

 ATTRIBUTE DESCRIPTION

QueryExecutionEndTimeUTC Time when the query execution completed.

QueryExecutionDuration (ms) Duration for a query execution.

QueryType Type of query. For instance, the query passed could be a

Power BI refresh or DirectQuery. Or, it could be queries from
PowerApps and Microsoft Flow.

DataProcessingEndTimeUTC Time when data processing activities like spooling, data

retrieval, compression, and data processing completed.

DataProcessingDuration (ms) Duration for data processing activities like spooling, data
retrieval, compression, and data processing.

Success Indicates if the query succeeded or failed.

ErrorMessage If the query failed, indicates the error message.

The Query Execution Aggregation Report contains query information aggregated to a time interval by
GatewayObjectId, DataSource, Success, and QueryType. The default value is 5 minutes, but you can adjust it.
The following attributes are captured.

ATTRIBUTE DESCRIPTION

GatewayObjectId Unique identifier for the gateway.

AggregationStartTimeUTC Start of the time window for which query attributes were
aggregated.

AggregationEndTimeUTC End of the time window for which query attributes were
aggregated.

DataSource Contains both the data source type and data source.

Success Indicates if the query succeeded or failed.

AverageQueryExecutionDuration (ms) Average query execution time for the aggregation time
window.

MaxQueryExecutionDuration (ms) Maximum query execution time for the aggregation time
window.

MinQueryExecutionDuration (ms) Minimum query execution time for the aggregation time
window.

QueryType Type of query. For instance, the query passed could be a

Power BI refresh or DirectQuery. Or, it could be queries from
PowerApps and Microsoft Flow.
 ATTRIBUTE DESCRIPTION

AverageDataProcessingDuration (ms) Average time for data processing activities like spooling, data
retrieval, compression, and data processing for the
aggregation time window.

MaxDataProcessingDuration (ms) Maximum time for data processing activities like spooling,
data retrieval, compression, and data processing for the
aggregation time window.

MinDataProcessingDuration (ms) Minimum time for data processing activities like spooling, data
retrieval, compression, and data processing for the
aggregation time window.

Count Number of queries.

The System Counter Aggregation Report contains system counter values aggregated to a time interval. The
default value is 5 minutes, but you can adjust it. The following attributes are captured.

ATTRIBUTE DESCRIPTION

GatewayObjectId Unique identifier for the gateway.

AggregationStartTimeUTC Start of the time window for the system counters that were
aggregated.

AggregationEndTimeUTC End of the time window for the system counters that were
aggregated.

CounterName System counters, which includes memory and CPU usage by

the gateway, Mashup Engine, and overall by the machine
hosting the gateway.

Max Maximum value for the system counter for the aggregation
time window.

Min Minimum value for the system counter for the aggregation
time window.

Average Average value for the system counter for the aggregation
time window.

Visualize gateway performance

Now, you can visualize the data that's in the log files.
1. Download the Gateway Performance PBI template, and open it by using Power BI Desktop.
2. In the dialog box that opens, check that the folder path matches the value in ReportFilePath.
3. Select Load, and the template file starts loading the data from your log files. All visuals are populated by
using the data in the reports.
4. Optionally, save this file as a PBIX, and publish it to your service for automatic refreshes.
You also can customize this template file to suit your needs. For more information on Power BI templates, see this
Microsoft Power BI blog post.

Next steps
Troubleshooting tools
 PowerShell support for on-premises data gateway
clusters
7/17/2019 • 3 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback
on this article, or the overall gateway docs experience, scroll to the bottom of the article.

PowerShell scripts are available in the on-premises data gateway installation folder. By default, that folder is
C:\Program Files\On-premises data gateway. You must be using PowerShell version 5 or newer for these scripts
to work correctly. The PowerShell scripts let users perform the following operations:
Retrieve the list of gateway clusters available for a user
Retrieve the list of gateway instances registered in a cluster, as well as their online or offline status
Modify the enable/disable status for a gateway instance within a cluster, as well as other gateway properties
Delete a gateway

Run the PowerShell commands

To run the on-premises data gateway PowerShell commands, you first need to take the following steps:
1. Open a PowerShell command window as an Administrator.
2. Run the following one-time PowerShell command (this presumes you've never run PowerShell commands
on the current machine):

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force

3. Navigate to the on-premises data gateway installation folder in the PowerShell window, and import the
necessary module using the following command:

Import-Module .\OnPremisesDataGatewayHAMgmt.psm1

Once those steps are complete, you can use the commands in the following table to manage your gateway clusters.

COMMAND DESCRIPTION PARAMETERS

Login-OnPremisesDataGateway This command allows you to sign in to AAD username and password (provided
manage your on-premises data as part of the command execution, not
gateway clusters. You must run this initial invocation)
command and sign in before other high
availability commands can work
properly. Note: AAD auth token
acquired as part of a Login call is only
valid for 1 hour, after which it expires.
You can rerun the Login command to
acquire a new token.
 COMMAND DESCRIPTION PARAMETERS

Get-OnPremisesDataGatewayClusters Retrieves the list of gateway clusters for Optionally, you can pass formatting
the logged in user. parameters to this command for better
readability, such as Format-Table -
AutoSize -Wrap

Get-OnPremisesDataClusterGateways Retrieves the list of gateways within the -ClusterObjectID xyz (where xyz is
specified cluster, as well as additional replaced with an actual cluster object ID
information for each gateway value, which can be retrieved using the
(online/offline status, machine name, so Get-OnPremisesDataGatewayClusters
on) command)

Set-OnPremisesDataGateway Lets you set property values for a given -ClusterObjectID xyz (where xyz is
gateway within a cluster, including the replaced with an actual cluster object ID
ability to enable or disable a specific value, which can be retrieved using the
gateway instance Get-OnPremisesDataGatewayClusters
command) -GatewayObjectID abc
(where abc is replaced with an actual
gateway object ID value, which can be
retrieved using the Get-
OnPremisesDataClusterGateways
command, given a cluster object ID)

Get-OnPremisesDataGatewayStatus Lets you retrieve the status for a given -ClusterObjectID xyz (where xyz is
gateway instance within a cluster replaced with an actual cluster object ID
value, which can be retrieved using the
Get-OnPremisesDataGatewayClusters
command) -GatewayObjectID abc
(where abc is replaced with an actual
gateway object ID value, which can be
retrieved using the Get-
OnPremisesDataClusterGateways
command, given a cluster object ID)

Remove-OnPremisesDataGateway Lets you remove a gateway instance -ClusterObjectID xyz (where xyz is
from a cluster. Note: the primary replaced with an actual cluster object ID
gateway in the cluster cannot be value, which can be retrieved using the
removed until all other gateways in the Get-OnPremisesDataGatewayClusters
cluster are removed. command) -GatewayObjectID abc
(where abc is replaced with an actual
gateway object ID value, which can be
retrieved using the Get-
OnPremisesDataClusterGateways
command, given a cluster object ID)

Next steps
On-premises data gateway app
Manage high availability clusters and load balancing
Remove or delete an on-premises data gateway
 Previous monthly updates to the on-premises data
gateway
7/17/2019 • 2 minutes to read • Edit Online

NOTE
We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general
content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback on
this article, or the overall gateway docs experience, scroll to the bottom of the article.

This article describes the four previous updates for the on-premises data gateway and an option to download
any of these versions. For the most current July 2019 release of the gateway, check out our recent blog, or
download the latest version.

June 2019 Update (3000.6.204)

List of features released
Download the June 2019 version of on-premises data gateway
Download the May 2019 version of on-premises data gateway (personal-mode)

May 2019 Update (3000.5.185)

List of features released
Download the May 2019 version of on-premises data gateway
Download the May 2019 version of on-premises data gateway (personal-mode)

April 2019 Update (3000.3.138)

List of features released
Download the April 2019 version of on-premises data gateway
Download the April 2019 version of on-premises data gateway (personal-mode)

March 2019 Update (3000.2.52)

List of features released
Download the March 2019 version of on-premises data gateway
Download the March 2019 version of on-premises data gateway (personal-mode)