shutdown() | Respan Docs

Overview

shutdown() flushes pending spans and gracefully closes the tracer. Use it when your application is intentionally stopping tracing, such as in long-running servers, workers, signal handlers, or test teardown. Short-lived Node.js scripts do not need shutdown() solely to export their final spans because the SDK drains pending spans on normal process exit.

Signature

async shutdown(): Promise<void>

Basic Usage

import { RespanTelemetry } from '@respan/tracing';
const respanAi = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY,
    appName: 'my-app'
});
await respanAi.initialize();
await respanAi.withWorkflow(
    { name: 'my_workflow' },
    async () => {
        return await processData();
    }
);
// Close the tracer when this process is done tracing
await respanAi.shutdown();
console.log('Tracing shutdown complete');

Complete Application Lifecycle

async function main() {
    const respanAi = new RespanTelemetry({
        apiKey: process.env.RESPAN_API_KEY,
        appName: 'my-app'
    });
    
    try {
        // Initialize
        await respanAi.initialize();
        console.log('Tracing initialized');
        
        // Run your application
        await respanAi.withWorkflow(
            { name: 'main_workflow' },
            async () => {
                return await runApplication();
            }
        );
    } catch (error) {
        console.error('Application error:', error);
    } finally {
        // Always shutdown, even on error
        await respanAi.shutdown();
        console.log('Tracing shutdown complete');
    }
}
main();

Graceful Shutdown on Signals

const respanAi = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY,
    appName: 'my-server'
});
await respanAi.initialize();
// Handle shutdown signals
process.on('SIGTERM', async () => {
    console.log('SIGTERM received, shutting down gracefully...');
    await respanAi.shutdown();
    process.exit(0);
});
process.on('SIGINT', async () => {
    console.log('SIGINT received, shutting down gracefully...');
    await respanAi.shutdown();
    process.exit(0);
});
// Run application
await runServer();

Express Application

import express from 'express';
const app = express();
const respanAi = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY,
    appName: 'api-server'
});
await respanAi.initialize();
app.get('/api/data', async (req, res) => {
    await respanAi.withWorkflow(
        { name: 'api_request' },
        async () => {
            const data = await fetchData();
            res.json(data);
        }
    );
});
const server = app.listen(3000, () => {
    console.log('Server running on port 3000');
});
// Graceful shutdown
async function gracefulShutdown() {
    console.log('Shutting down gracefully...');
    
    // Stop accepting new requests
    server.close(async () => {
        console.log('HTTP server closed');
        
        // Shutdown tracing
        await respanAi.shutdown();
        console.log('Tracing shutdown complete');
        
        process.exit(0);
    });
    
    // Force exit after 10 seconds
    setTimeout(() => {
        console.error('Forced shutdown after timeout');
        process.exit(1);
    }, 10000);
}
process.on('SIGTERM', gracefulShutdown);
process.on('SIGINT', gracefulShutdown);

Worker/Job Processing

async function processJobs() {
    const respanAi = new RespanTelemetry({
        apiKey: process.env.RESPAN_API_KEY,
        appName: 'job-worker'
    });
    
    await respanAi.initialize();
    
    let shouldStop = false;
    
    process.on('SIGTERM', () => {
        console.log('Stopping job processing...');
        shouldStop = true;
    });
    
    try {
        while (!shouldStop) {
            const job = await getNextJob();
            
            if (job) {
                await respanAi.withWorkflow(
                    { name: 'process_job' },
                    async () => {
                        return await processJob(job);
                    }
                );
            } else {
                await new Promise(resolve => setTimeout(resolve, 1000));
            }
        }
    } finally {
        await respanAi.shutdown();
        console.log('Worker shutdown complete');
    }
}
processJobs();

CLI Application

#!/usr/bin/env node
import { program } from 'commander';
async function runCLI() {
    const respanAi = new RespanTelemetry({
        apiKey: process.env.RESPAN_API_KEY,
        appName: 'cli-tool'
    });
    
    await respanAi.initialize();
    
    program
        .command('process <file>')
        .action(async (file) => {
            try {
                await respanAi.withWorkflow(
                    { name: 'cli_process' },
                    async () => {
                        return await processFile(file);
                    }
                );
                console.log('Processing complete');
            } catch (error) {
                console.error('Error:', error);
                process.exit(1);
            } finally {
                await respanAi.shutdown();
            }
        });
    
    await program.parseAsync();
}
runCLI();

Testing

import { describe, it, beforeAll, afterAll } from '@jest/globals';
describe('My Service', () => {
    let respanAi: RespanTelemetry;
    
    beforeAll(async () => {
        respanAi = new RespanTelemetry({
            apiKey: process.env.RESPAN_API_KEY,
            appName: 'test-suite'
        });
        await respanAi.initialize();
    });
    
    afterAll(async () => {
        // Shutdown after all tests
        await respanAi.shutdown();
    });
    
    it('should process data', async () => {
        await respanAi.withWorkflow(
            { name: 'test_workflow' },
            async () => {
                const result = await processData();
                expect(result).toBeDefined();
            }
        );
    });
});

What shutdown() Does

Flushes all pending spans - Sends any buffered spans to Respan
Closes the tracer - Gracefully closes the OpenTelemetry tracer
Cleans up resources - Releases any held resources

shutdown() vs flush()

Method	Purpose
`shutdown()`	Complete cleanup, sends pending data, and closes the tracer
`flush()`	Sends pending data but keeps the tracer active for more spans
Automatic Node.js exit drain	Sends pending data on normal process exit without closing it manually

Best Practices

Use shutdown() for long-running applications, workers, explicit signal handling, and test teardown
Use in finally blocks when your code owns a terminal tracing lifecycle
Handle SIGTERM and SIGINT signals for graceful shutdown
Set a timeout for forced shutdown if graceful shutdown takes too long
In testing, shutdown after all tests complete
Never reuse the tracer after calling shutdown()
For serverless, you might prefer flush() over shutdown() if the environment is reused