Transaction Management

/**
 * Give the current transaction a custom name. Overrides any automatic naming rules.
 * Must be called within an active transaction context.
 * @param {string} name - The name for the transaction. Will be prefixed with 'Custom/'
 */
function setTransactionName(name);

const newrelic = require('newrelic');

app.post('/api/users', (req, res) => {
  newrelic.setTransactionName('CreateUser');
  // ... handle user creation
});

/**
 * Name transaction using controller/action pattern. Will be prefixed with 'Controller/'
 * @param {string} name - The controller name
 * @param {string} [action] - The action name. Defaults to HTTP method if omitted
 */
function setControllerName(name, action);

app.get('/users/:id', (req, res) => {
  newrelic.setControllerName('UserController', 'show');
  // ... handle user retrieval
});

/**
 * Returns a handle to the current transaction with control methods
 * @returns {TransactionHandle|TransactionHandleStub} Transaction handle or stub if no transaction
 */
function getTransaction();

function processLongRunningTask() {
  const transaction = newrelic.getTransaction();
  
  setTimeout(() => {
    // Do work...
    transaction.end(); // Manually end the transaction
  }, 5000);
}

/**
 * Creates and starts a web transaction. Transaction ends automatically unless
 * getTransaction() is called within the handler.
 * @param {string} url - The URL/name for the transaction
 * @param {Function} handle - Function containing the transaction work
 * @returns {*} The return value of the handle function
 */
function startWebTransaction(url, handle);

function handleCustomWebRequest(request) {
  return newrelic.startWebTransaction('/api/custom-endpoint', () => {
    // Process the request
    return processRequest(request);
  });
}

// For manual transaction control
function handleAsyncWebRequest(request) {
  return newrelic.startWebTransaction('/api/async-endpoint', () => {
    const transaction = newrelic.getTransaction();
    
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve(processRequest(request));
        transaction.end();
      }, 1000);
    });
  });
}

/**
 * Creates and starts a background transaction for non-web operations.
 * Transaction ends automatically unless getTransaction() is called within handler.
 * @param {string} name - The name for the transaction
 * @param {string} [group] - The transaction group. Defaults to 'Nodejs'
 * @param {Function} handle - Function containing the transaction work
 * @returns {*} The return value of the handle function
 */
function startBackgroundTransaction(name, group, handle);

// Simple background job
function processBatch() {
  return newrelic.startBackgroundTransaction('ProcessBatch', () => {
    return performBatchProcessing();
  });
}

// Background job with custom group
function generateReport() {
  return newrelic.startBackgroundTransaction('GenerateReport', 'Reports', () => {
    return createMonthlyReport();
  });
}

// Manual transaction control for background job
function processQueue() {
  return newrelic.startBackgroundTransaction('ProcessQueue', 'Jobs', () => {
    const transaction = newrelic.getTransaction();
    
    return processQueueItems().then((result) => {
      transaction.end();
      return result;
    });
  });
}

/**
 * Manually end the current transaction. Must be called within transaction context.
 */
function endTransaction();

app.get('/streaming-data', (req, res) => {
  // Start streaming response
  res.writeHead(200, { 'Content-Type': 'application/json' });
  
  // End the New Relic transaction early since streaming will continue
  newrelic.endTransaction();
  
  // Continue streaming data...
  streamData(res);
});

/**
 * End this specific transaction
 * @param {Function} [callback] - Optional callback to execute after transaction ends
 */
TransactionHandle.prototype.end = function(callback);

/**
 * Mark this transaction to be ignored (not sent to New Relic)
 */
TransactionHandle.prototype.ignore = function();

/**
 * Check if this transaction is being sampled
 * @returns {boolean} True if transaction is sampled
 */
TransactionHandle.prototype.isSampled = function();

/**
 * Accept and process incoming distributed trace headers
 * @param {string} transportType - Transport type (e.g., 'HTTP')
 * @param {object} headers - Incoming headers object
 */
TransactionHandle.prototype.acceptDistributedTraceHeaders = function(transportType, headers);

/**
 * Insert distributed trace headers for outgoing requests
 * @param {object} headers - Headers object to modify
 */
TransactionHandle.prototype.insertDistributedTraceHeaders = function(headers);

const transaction = newrelic.getTransaction();

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

// For incoming HTTP request
transaction.acceptDistributedTraceHeaders('HTTP', req.headers);

function handleLongOperation() {
  const transaction = newrelic.getTransaction();
  
  performAsyncOperation((err, result) => {
    if (err) {
      newrelic.noticeError(err);
    }
    transaction.end();
  });
}

app.get('/health-check', (req, res) => {
  const transaction = newrelic.getTransaction();
  transaction.ignore(); // Don't track health checks
  
  res.json({ status: 'ok' });
});

app.post('/api/:resource/:action', (req, res) => {
  const { resource, action } = req.params;
  newrelic.setTransactionName(`${resource}/${action}`);
  
  // Handle the request...
});