You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how to enable tracing on Linux and macOS with the Microsoft ODBC Driver for SQL Server to output a log file when troubleshooting application behavior.
2
+
title: Data access tracing on Linux and macOS
3
+
description: Learn how to enable tracing on Linux and macOS with the Microsoft ODBC Driver for SQL Server. You can output a log file when you're troubleshooting application behavior.
The unixODBC Driver Manager on macOS and Linux supports tracing of ODBC API call entry and exit of the ODBC Driver for [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)].
23
23
24
-
To trace your application's ODBC behavior, edit the `odbcinst.ini` file's `[ODBC]` section to set the values `Trace=Yes` and `TraceFile`
25
-
to the path of the file that is to contain the trace output. For example:
24
+
To trace your application's ODBC behavior, edit the `[ODBC]` section of the `odbcinst.ini` file. Set the values `Trace=Yes` and `TraceFile` to the path of the file that will contain the trace output. For example:
26
25
27
26
```ini
28
27
[ODBC]
29
28
Trace=Yes
30
29
TraceFile=/home/myappuser/odbctrace.log
31
30
```
32
31
33
-
(You may also use `/dev/stdout` or any other device name to send trace output there instead of to a persistent file.) With the above settings, every time an application loads the unixODBC Driver Manager, it will record all ODBC API calls made, into the output file.
32
+
You can also use `/dev/stdout` or any other device name to send trace output there, instead of to a persistent file. With the preceding settings, every time an application loads the unixODBC Driver Manager, it records all ODBC API calls made, into the output file.
34
33
35
-
After you finish tracing your application, remove `Trace=Yes` from the `odbcinst.ini` file to avoid the performance penalty of tracing, and ensure any unnecessary trace files are removed.
34
+
After you finish tracing your application, remove `Trace=Yes` from the `odbcinst.ini` file to avoid the performance penalty of tracing, and ensure that any unnecessary trace files are removed.
36
35
37
-
Tracing applies to all applications that use the driver in `odbcinst.ini`. To not trace all applications (for example, to avoid disclosing sensitive per-user information), you can trace an individual application instance by providing it the location of a private `odbcinst.ini`, using the `ODBCSYSINI` environment variable. For example:
36
+
Tracing applies to all applications that use the driver in `odbcinst.ini`. To not trace all applications (for example, to avoid disclosing sensitive per-user information), you can trace an individual application instance. Provide the instance the location of a private `odbcinst.ini`, by using the `ODBCSYSINI` environment variable. For example:
38
37
39
38
```bash
40
39
$ ODBCSYSINI=/home/myappuser myapp
41
40
```
42
41
43
42
In this case, you can add `Trace=Yes` to the `[ODBC Driver 17 for SQL Server]` section of `/home/myappuser/odbcinst.ini`.
44
43
45
-
## Determining which odbc.ini file the driver is using
44
+
## Determine which file the driver is using
46
45
47
-
The Linux and macOS ODBC drivers don't know which `odbc.ini` is in use, or the path to the `odbc.ini` file. However, information about which `odbc.ini` file is in use is available from the unixODBC tools `odbc_config` and `odbcinst`, and from the unixODBC Driver Manager documentation.
46
+
The Linux and macOS ODBC drivers don't know which `odbc.ini`file is in use, or the path to the `odbc.ini` file. Information about which `odbc.ini` file is in use is available from the unixODBC tools `odbc_config` and `odbcinst`. You can also get this information from the unixODBC Driver Manager documentation.
48
47
49
-
For example, the following command prints (among other information) the location of system and user `odbc.ini` files that contain, respectively, system and user DSNs:
48
+
For example, the following command prints the location of system and user `odbc.ini` files that contain, respectively, system and user data source names (DSNs):
50
49
51
50
```bash
52
51
$ odbcinst -j
@@ -60,12 +59,8 @@ SQLLEN Size........: 8
60
59
SQLSETPOSIROW Size.: 8
61
60
```
62
61
63
-
The [unixODBC documentation](http://www.unixodbc.org/doc/UserManual/) explains the differences between user and system DSNs. In summary:
64
-
65
-
- User DSNs - DSNs that are only available to a specific user. Users can connect using, add, modify, and remove their own user DSNs. User DSNs are stored in a file in the user's home directory, or a subdirectory.
66
-
67
-
- System DSNs - these DSNs are available for every user on the system to connect using them, but can only be added, modified, and removed by a system administrator. If a user has a user DSN with the same name as a system DSN, the user DSN will be used upon connections by that user.
62
+
*User DSNs* are only available to a specific user. User DSNs are stored in a file in the user's home directory, or a subdirectory. *System DSNs* are available for every user on the system, but can only be added, modified, and removed by a system administrator. If a user has a user DSN with the same name as a system DSN, the user DSN will be used upon connections by that user. For more information, see the [unixODBC documentation](http://www.unixodbc.org/doc/UserManual/).
The ODBC drivers for Linux and macOS support [!INCLUDE[ssHADR](../../../includes/sshadr_md.md)]. For more information about [!INCLUDE[ssHADR](../../../includes/sshadr_md.md)], see:
19
+
The ODBC drivers for Linux and macOS support Always On availability groups. For more information about Always On availability groups, see:
20
20
21
-
-[Availability Group Listeners, Client Connectivity, and Application Failover (SQL Server)](../../../database-engine/availability-groups/windows/listeners-client-connectivity-application-failover.md)
21
+
-[Availability group listeners, client connectivity, and application failover (SQL Server)](../../../database-engine/availability-groups/windows/listeners-client-connectivity-application-failover.md)
22
22
23
-
-[Creation and Configuration of Availability Groups (SQL Server)](../../../database-engine/availability-groups/windows/creation-and-configuration-of-availability-groups-sql-server.md)
23
+
-[Creation and configuration of availability groups (SQL Server)](../../../database-engine/availability-groups/windows/creation-and-configuration-of-availability-groups-sql-server.md)
24
24
25
-
-[Failover Clustering and AlwaysOn Availability Groups (SQL Server)](../../../database-engine/availability-groups/windows/failover-clustering-and-always-on-availability-groups-sql-server.md)
25
+
-[Failover clustering and Always On availability groups (SQL Server)](../../../database-engine/availability-groups/windows/failover-clustering-and-always-on-availability-groups-sql-server.md)
-[Active secondaries: Readable secondary replicas (Always On availability groups)](../../../database-engine/availability-groups/windows/active-secondaries-readable-secondary-replicas-always-on-availability-groups.md)
28
28
29
-
You can specify the availability group listener of a given availability group in the connection string. If an ODBC application on Linux or macOS is connected to a database in an availability group that fails over, the original connection is broken and the application must open a new connection to continue work after the failover.
29
+
You can specify the availability group listener of a particular availability group in the connection string. If an ODBC application on Linux or macOS is connected to a database in an availability group that fails over, the original connection is broken. The application must open a new connection to continue work after the failover.
30
30
31
-
The ODBC drivers on Linux and macOS iterate sequentially through all IP addresses associated with a DNS hostname if you aren't connecting to an availability group listener, and multiple IP addresses are associated with the hostname.
31
+
The ODBC drivers on Linux and macOS iterate sequentially through all IP addresses associated with a DNS hostname, if you aren't connecting to an availability group listener. If the DNS server's first returned IP address isn't connectable, these iterations can be time consuming.
32
32
33
-
If the DNS server's first returned IP address isn't connectable, these iterations can be time consuming. When connecting to an availability group listener, the driver attempts to establish connections to all IP addresses in parallel. If a connection attempt succeeds, the driver discards any pending connection attempts.
33
+
When you're connecting to an availability group listener, the driver attempts to establish connections to all IP addresses in parallel. If a connection attempt succeeds, the driver discards any pending connection attempts.
34
34
35
35
> [!NOTE]
36
-
> Because a connection can fail due to an availability group failover, implement connection retry logic; retry a failed connection until it reconnects. Increasing connection timeout and implementing connection retry logic increases the chance of connecting to an availability group.
36
+
> Because a connection can fail due to an availability group failover, you should implement connection retry logic. Retry a failed connection until it reconnects. Increasing the connection timeout and implementing connection retry logic increases the chance of connecting to an availability group.
37
37
38
-
## Connecting with MultiSubnetFailover
38
+
## Connect with MultiSubnetFailover
39
39
40
-
Always specify **MultiSubnetFailover=Yes** when connecting to a [!INCLUDE[ssSQL11](../../../includes/sssql11-md.md)] availability group listener or [!INCLUDE[ssSQL11](../../../includes/sssql11-md.md)]Failover Cluster Instance. **MultiSubnetFailover** enables faster failover for all Availability Groups and failover cluster instance in [!INCLUDE[ssSQL11](../../../includes/sssql11-md.md)]. **MultiSubnetFailover** also significantly reduces failover time for single and multi-subnet AlwaysOn topologies. During a multisubnet failover, the client attempts connections in parallel. During a subnet failover, the driver aggressively retries the TCP connection.
40
+
Always specify `MultiSubnetFailover=Yes` when you're connecting to a [!INCLUDE[ssSQL11](../../../includes/sssql11-md.md)] availability group listener or [!INCLUDE[ssSQL11](../../../includes/sssql11-md.md)]failover cluster instance. `MultiSubnetFailover` enables faster failover for all availability groups and failover cluster instances in [!INCLUDE[ssSQL11](../../../includes/sssql11-md.md)].
41
41
42
-
The **MultiSubnetFailover**connection property indicates that the application is being deployed in an availability group or Failover Cluster Instance. The driver tries to connect to the database on the primary [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] instance by trying to connect to all the IP addresses. When connecting with **MultiSubnetFailover=Yes**, the client retries TCP connection attempts faster than the operating system's default TCP retransmit intervals. **MultiSubnetFailover=Yes** enables faster reconnection after failover of either an AlwaysOn Availability Group or an AlwaysOn Failover Cluster Instance. **MultiSubnetFailover=Yes** applies to both single- and multi-subnet Availability Groups and Failover Cluster Instances.
42
+
This connection property also significantly reduces failover time for single and multi-subnet Always On topologies. During a multi-subnet failover, the client attempts connections in parallel. During a subnet failover, the driver aggressively retries the TCP connection.
43
43
44
-
Use **MultiSubnetFailover=Yes** when connecting to an availability group listener or Failover Cluster Instance. Otherwise, your application's performance can be negatively affected.
44
+
The `MultiSubnetFailover` connection property indicates that the application is being deployed in an availability group or failover cluster instance. The driver tries to connect to the database on the primary [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] instance by trying to connect to all the IP addresses.
45
45
46
-
Note the following recommendations when connecting to a server in an availability group or Failover Cluster Instance:
46
+
When you connect with `MultiSubnetFailover=Yes`, the client retries TCP connection attempts faster than the operating system's default TCP retransmit intervals. `MultiSubnetFailover=Yes` enables faster reconnection after failover of either an Always On availability group, or an Always On failover cluster instance. `MultiSubnetFailover=Yes` applies to both single- and multi-subnet availability groups and failover cluster instances.
47
47
48
-
- Specify **MultiSubnetFailover=Yes** to improve performance when connecting to a single subnet or multi-subnet Availability Group.
48
+
Use `MultiSubnetFailover=Yes` when you're connecting to an availability group listener or failover cluster instance. Otherwise, your application's performance can be negatively affected.
49
+
50
+
### Recommendations
51
+
52
+
When you're connecting to a server in an availability group or failover cluster instance:
53
+
54
+
- Specify `MultiSubnetFailover=Yes` to improve performance when you're connecting to a single subnet or multi-subnet availability group.
49
55
50
56
- Specify the availability group listener of the availability group as the server in your connection string.
51
57
52
58
- You can't connect to a [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] instance configured with more than 64 IP addresses.
53
59
54
-
- Both [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] Authentication or Kerberos Authentication can be used with **MultiSubnetFailover=Yes** without affecting the behavior of the application.
60
+
- Both [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] Authentication or Kerberos Authentication can be used with `MultiSubnetFailover=Yes`, without affecting the behavior of the application.
55
61
56
-
- You can increase the value of **loginTimeout** to accommodate for failover time and reduce the application's connection retry attempts.
62
+
- You can increase the value of `loginTimeout` to accommodate for failover time and reduce the application's connection retry attempts.
57
63
58
64
- Distributed transactions aren't supported.
59
65
60
66
If read-only routing isn't in effect, connecting to a secondary replica location in an availability group fails in the following situations:
61
67
62
68
- If the secondary replica location isn't configured to accept connections.
63
69
64
-
- If an application uses **ApplicationIntent=ReadWrite** and the secondary replica location is configured for read-only access.
70
+
- If an application uses `ApplicationIntent=ReadWrite` and the secondary replica location is configured for read-only access.
65
71
66
-
A connection fails if a primary replica is configured to reject read-only workloads and the connection string contains **ApplicationIntent=ReadOnly**.
72
+
A connection fails if a primary replica is configured to reject read-only workloads, and the connection string contains `ApplicationIntent=ReadOnly`.
Two ODBC connection string keywords support [!INCLUDE[ssHADR](../../../includes/sshadr_md.md)]:
78
+
Two ODBC connection string keywords support Always On availability groups:
73
79
74
-
-**ApplicationIntent**
80
+
-`ApplicationIntent`
75
81
76
-
-**MultiSubnetFailover**
82
+
-`MultiSubnetFailover`
77
83
78
-
For more information about ODBC connection string keywords, see [Using Connection String Keywords with SQL Server Native Client](../../../relational-databases/native-client/applications/using-connection-string-keywords-with-sql-server-native-client.md).
84
+
For more information about ODBC connection string keywords, see [Using connection string keywords with SQL Server Native Client](../../../relational-databases/native-client/applications/using-connection-string-keywords-with-sql-server-native-client.md).
79
85
80
86
The equivalent connection attributes are:
81
87
82
-
-**SQL_COPT_SS_APPLICATION_INTENT**
88
+
-`SQL_COPT_SS_APPLICATION_INTENT`
83
89
84
-
-**SQL_COPT_SS_MULTISUBNET_FAILOVER**
90
+
-`SQL_COPT_SS_MULTISUBNET_FAILOVER`
85
91
86
92
For more information about ODBC connection attributes, see [SQLSetConnectAttr](../../../relational-databases/native-client-odbc-api/sqlsetconnectattr.md).
87
93
88
-
An ODBC application that uses [!INCLUDE[ssHADR](../../../includes/sshadr_md.md)] can use one of two functions to make the connection:
94
+
An ODBC application that uses Always On availability groups can use one of two functions to make the connection:
89
95
90
96
| Function | Description |
91
97
|--|--|
92
-
|[SQLConnect Function](../../../odbc/reference/syntax/sqlconnect-function.md)|**SQLConnect** supports both **ApplicationIntent** and **MultiSubnetFailover** via a data source name (DSN) or connection attribute. |
93
-
|[SQLDriverConnect Function](../../../odbc/reference/syntax/sqldriverconnect-function.md)|**SQLDriverConnect** supports **ApplicationIntent** and **MultiSubnetFailover** via DSN, connection string keyword, or connection attribute. |
98
+
|[SQLConnect Function](../../../odbc/reference/syntax/sqlconnect-function.md)|`SQLConnect` supports both `ApplicationIntent` and `MultiSubnetFailover` via a data source name (DSN) or connection attribute. |
99
+
|[SQLDriverConnect Function](../../../odbc/reference/syntax/sqldriverconnect-function.md)|`SQLDriverConnect` supports `ApplicationIntent` and `MultiSubnetFailover` via DSN, connection string keyword, or connection attribute. |
94
100
95
101
## See also
96
102
97
-
[Connection String Keywords and Data Source Names (DSNs)](connection-string-keywords-and-data-source-names-dsns.md)
103
+
[Connection string keywords and data source names (DSNs)](connection-string-keywords-and-data-source-names-dsns.md)
0 commit comments