0
# Transaction Management
1

2
Core transaction lifecycle management for web requests and background jobs. Provides manual control over transaction naming, timing, and metadata.
3

4
## Capabilities
5

6
### Set Transaction Name
7

8
Override automatic transaction naming with a custom name.
9

10
```javascript { .api }
11
/**
12
 * Give the current transaction a custom name. Overrides any automatic naming rules.
13
 * Must be called within an active transaction context.
14
 * @param {string} name - The name for the transaction. Will be prefixed with 'Custom/'
15
 */
16
function setTransactionName(name);
17
```
18

19
**Usage Example:**
20

21
```javascript
22
const newrelic = require('newrelic');
23

24
app.post('/api/users', (req, res) => {
25
  newrelic.setTransactionName('CreateUser');
26
  // ... handle user creation
27
});
28
```
29

30
### Set Controller Name
31

32
Name transaction using controller/action pattern, typically for MVC frameworks.
33

34
```javascript { .api }
35
/**
36
 * Name transaction using controller/action pattern. Will be prefixed with 'Controller/'
37
 * @param {string} name - The controller name
38
 * @param {string} [action] - The action name. Defaults to HTTP method if omitted
39
 */
40
function setControllerName(name, action);
41
```
42

43
**Usage Example:**
44

45
```javascript
46
app.get('/users/:id', (req, res) => {
47
  newrelic.setControllerName('UserController', 'show');
48
  // ... handle user retrieval
49
});
50
```
51

52
### Get Transaction Handle
53

54
Get a handle to the current transaction for manual control over its lifecycle.
55

56
```javascript { .api }
57
/**
58
 * Returns a handle to the current transaction with control methods
59
 * @returns {TransactionHandle|TransactionHandleStub} Transaction handle or stub if no transaction
60
 */
61
function getTransaction();
62
```
63

64
**Usage Example:**
65

66
```javascript
67
function processLongRunningTask() {
68
  const transaction = newrelic.getTransaction();
69
  
70
  setTimeout(() => {
71
    // Do work...
72
    transaction.end(); // Manually end the transaction
73
  }, 5000);
74
}
75
```
76

77
### Start Web Transaction
78

79
Create and start a web transaction for custom HTTP-like operations.
80

81
```javascript { .api }
82
/**
83
 * Creates and starts a web transaction. Transaction ends automatically unless
84
 * getTransaction() is called within the handler.
85
 * @param {string} url - The URL/name for the transaction
86
 * @param {Function} handle - Function containing the transaction work
87
 * @returns {*} The return value of the handle function
88
 */
89
function startWebTransaction(url, handle);
90
```
91

92
**Usage Example:**
93

94
```javascript
95
function handleCustomWebRequest(request) {
96
  return newrelic.startWebTransaction('/api/custom-endpoint', () => {
97
    // Process the request
98
    return processRequest(request);
99
  });
100
}
101

102
// For manual transaction control
103
function handleAsyncWebRequest(request) {
104
  return newrelic.startWebTransaction('/api/async-endpoint', () => {
105
    const transaction = newrelic.getTransaction();
106
    
107
    return new Promise((resolve) => {
108
      setTimeout(() => {
109
        resolve(processRequest(request));
110
        transaction.end();
111
      }, 1000);
112
    });
113
  });
114
}
115
```
116

117
### Start Background Transaction
118

119
Create and start a background transaction for non-web operations like batch jobs.
120

121
```javascript { .api }
122
/**
123
 * Creates and starts a background transaction for non-web operations.
124
 * Transaction ends automatically unless getTransaction() is called within handler.
125
 * @param {string} name - The name for the transaction
126
 * @param {string} [group] - The transaction group. Defaults to 'Nodejs'
127
 * @param {Function} handle - Function containing the transaction work
128
 * @returns {*} The return value of the handle function
129
 */
130
function startBackgroundTransaction(name, group, handle);
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
// Simple background job
137
function processBatch() {
138
  return newrelic.startBackgroundTransaction('ProcessBatch', () => {
139
    return performBatchProcessing();
140
  });
141
}
142

143
// Background job with custom group
144
function generateReport() {
145
  return newrelic.startBackgroundTransaction('GenerateReport', 'Reports', () => {
146
    return createMonthlyReport();
147
  });
148
}
149

150
// Manual transaction control for background job
151
function processQueue() {
152
  return newrelic.startBackgroundTransaction('ProcessQueue', 'Jobs', () => {
153
    const transaction = newrelic.getTransaction();
154
    
155
    return processQueueItems().then((result) => {
156
      transaction.end();
157
      return result;
158
    });
159
  });
160
}
161
```
162

163
### End Transaction
164

165
Manually end the current web or background transaction.
166

167
```javascript { .api }
168
/**
169
 * Manually end the current transaction. Must be called within transaction context.
170
 */
171
function endTransaction();
172
```
173

174
**Usage Example:**
175

176
```javascript
177
app.get('/streaming-data', (req, res) => {
178
  // Start streaming response
179
  res.writeHead(200, { 'Content-Type': 'application/json' });
180
  
181
  // End the New Relic transaction early since streaming will continue
182
  newrelic.endTransaction();
183
  
184
  // Continue streaming data...
185
  streamData(res);
186
});
187
```
188

189
## Transaction Handle Methods
190

191
When you call `getTransaction()`, you receive a `TransactionHandle` object with the following methods:
192

193
### End Transaction
194

195
```javascript { .api }
196
/**
197
 * End this specific transaction
198
 * @param {Function} [callback] - Optional callback to execute after transaction ends
199
 */
200
TransactionHandle.prototype.end = function(callback);
201
```
202

203
### Ignore Transaction
204

205
```javascript { .api }
206
/**
207
 * Mark this transaction to be ignored (not sent to New Relic)
208
 */
209
TransactionHandle.prototype.ignore = function();
210
```
211

212
### Check Sampling Status
213

214
```javascript { .api }
215
/**
216
 * Check if this transaction is being sampled
217
 * @returns {boolean} True if transaction is sampled
218
 */
219
TransactionHandle.prototype.isSampled = function();
220
```
221

222
### Distributed Tracing Headers
223

224
```javascript { .api }
225
/**
226
 * Accept and process incoming distributed trace headers
227
 * @param {string} transportType - Transport type (e.g., 'HTTP')
228
 * @param {object} headers - Incoming headers object
229
 */
230
TransactionHandle.prototype.acceptDistributedTraceHeaders = function(transportType, headers);
231

232
/**
233
 * Insert distributed trace headers for outgoing requests
234
 * @param {object} headers - Headers object to modify
235
 */
236
TransactionHandle.prototype.insertDistributedTraceHeaders = function(headers);
237
```
238

239
**Distributed Tracing Example:**
240

241
```javascript
242
const transaction = newrelic.getTransaction();
243

244
// For outgoing HTTP request
245
const headers = {};
246
transaction.insertDistributedTraceHeaders(headers);
247
// headers now contains distributed tracing information
248

249
// For incoming HTTP request
250
transaction.acceptDistributedTraceHeaders('HTTP', req.headers);
251
```
252

253
## Common Patterns
254

255
### Long-Running Operations
256

257
```javascript
258
function handleLongOperation() {
259
  const transaction = newrelic.getTransaction();
260
  
261
  performAsyncOperation((err, result) => {
262
    if (err) {
263
      newrelic.noticeError(err);
264
    }
265
    transaction.end();
266
  });
267
}
268
```
269

270
### Ignoring Certain Transactions
271

272
```javascript
273
app.get('/health-check', (req, res) => {
274
  const transaction = newrelic.getTransaction();
275
  transaction.ignore(); // Don't track health checks
276
  
277
  res.json({ status: 'ok' });
278
});
279
```
280

281
### Custom Transaction Names with Context
282

283
```javascript
284
app.post('/api/:resource/:action', (req, res) => {
285
  const { resource, action } = req.params;
286
  newrelic.setTransactionName(`${resource}/${action}`);
287
  
288
  // Handle the request...
289
});
290
```