0
# Utilities
1

2
Miscellaneous utility functions for SQL obfuscation, performance tuning, and agent lifecycle management.
3

4
## Capabilities
5

6
### SQL Obfuscation
7

8
Obfuscate SQL queries for security purposes.
9

10
```javascript { .api }
11
/**
12
 * Obfuscate SQL queries for security
13
 * @param {string} sql - SQL statement to obfuscate
14
 * @param {string} dialect - Database dialect ('mysql', 'postgres', 'cassandra', 'oracle')
15
 * @returns {string} Obfuscated SQL with parameters replaced
16
 */
17
function obfuscateSql(sql, dialect);
18
```
19

20
### Ignore Apdex
21

22
Exclude current transaction from Apdex score calculations.
23

24
```javascript { .api }
25
/**
26
 * Ignore current transaction when calculating Apdex score.
27
 * Useful for very short or very long transactions that skew metrics.
28
 */
29
function ignoreApdex();
30
```
31

32
### Set Dispatcher
33

34
Set dispatcher environment information.
35

36
```javascript { .api }
37
/**
38
 * Set dispatcher name and version for environment reporting
39
 * @param {string} name - Dispatcher name (e.g., 'nginx', 'apache')
40
 * @param {string} [version] - Dispatcher version
41
 */
42
function setDispatcher(name, version);
43
```
44

45
### Shutdown Agent
46

47
Gracefully shut down the New Relic agent.
48

49
```javascript { .api }
50
/**
51
 * Gracefully shut down the agent with optional data collection
52
 * @param {object} [options] - Shutdown options
53
 * @param {boolean} [options.collectPendingData] - Send pending data before shutdown
54
 * @param {number} [options.timeout] - Timeout in milliseconds
55
 * @param {boolean} [options.waitForIdle] - Wait for active transactions to complete
56
 * @param {Function} [callback] - Callback executed after shutdown
57
 */
58
function shutdown(options, callback);
59
```
60

61
**Usage Examples:**
62

63
```javascript
64
const newrelic = require('newrelic');
65

66
// Obfuscate SQL for logging
67
const obfuscated = newrelic.obfuscateSql(
68
  "SELECT * FROM users WHERE id = 123 AND name = 'John'",
69
  'mysql'
70
);
71
console.log(obfuscated); // "SELECT * FROM users WHERE id = ? AND name = ?"
72

73
// Ignore Apdex for file downloads
74
app.get('/download/:file', (req, res) => {
75
  newrelic.ignoreApdex(); // Don't include in Apdex calculations
76
  res.download(path.join(__dirname, 'files', req.params.file));
77
});
78

79
// Set dispatcher information
80
newrelic.setDispatcher('nginx', '1.18.0');
81

82
// Graceful shutdown
83
process.on('SIGTERM', () => {
84
  newrelic.shutdown({
85
    collectPendingData: true,
86
    timeout: 5000,
87
    waitForIdle: true
88
  }, (error) => {
89
    if (error) {
90
      console.error('Error during New Relic shutdown:', error);
91
    } else {
92
      console.log('New Relic agent shut down successfully');
93
    }
94
    process.exit(0);
95
  });
96
});
97
```
98

99
## Shutdown Options
100

101
```javascript { .api }
102
interface ShutdownOptions {
103
  /** Send pending data to New Relic before shutdown */
104
  collectPendingData?: boolean;
105
  /** Maximum time to wait for shutdown in milliseconds */
106
  timeout?: number;
107
  /** Wait for active transactions to complete before shutdown */
108
  waitForIdle?: boolean;
109
}
110
```