Migrate from v1 to v2

What Changed

headers = {'DD-API-KEY': 'YOUR_API_KEY'}

headers = {'Authorization': 'Bearer YOUR_APP_KEY'}

data = [{'metric': 'my.metric', 'points': [[timestamp, value]]}]

data = {'series': [{'metric': 'my.metric', 'points': [[timestamp, value]]}]}

/api/v1/series

/api/v2/series

Migration Steps

1. 1

   Review Datadog API v2 Documentation

   code

   Familiarize yourself with the v2 API documentation, paying close attention to authentication, request/response formats, and new endpoints. Understand the scope of changes compared to v1.

   • ↳Focus on changes in authentication and data submission endpoints.
   • ↳Note rate limits and pagination differences in v2.
2. 2

   Update Authentication Credentials

   config

   Generate and configure new application keys or OAuth tokens in your Datadog account. Update your application's configuration or environment variables to use these new credentials.

   • ↳Securely store your new API keys/tokens.
   • ↳Ensure your CI/CD pipeline is updated with the new secrets.
3. 3

   Modify API Request Logic

   code

   Adapt your code to the new v2 API structure. This involves changing how you construct request payloads for metrics, logs, and traces, and updating the target endpoint URLs.

   • ↳Use Datadog's official SDKs if available, as they often handle version differences.
   • ↳Consider using a library for JSON manipulation to simplify payload construction.
4. 4

   Implement Error Handling for v2

   code

   Update your error handling logic to account for new error codes and response formats in v2. This ensures graceful degradation and easier debugging when issues arise.

   • ↳Log detailed error messages from the Datadog API.
   • ↳Map v2 error codes to your internal alerting system.
5. 5

   Develop and Run Integration Tests

   test

   Write comprehensive integration tests that cover the modified API interactions. These tests should validate data submission, retrieval, and error scenarios against a test Datadog environment or mock service.

   • ↳Use a dedicated testing environment or sandbox account.
   • ↳Test edge cases and rate limiting behavior.
6. 6

   Phased Rollout and Monitoring

   deploy

   Deploy the updated code to a small subset of your environment first. Closely monitor performance, error rates, and Datadog ingestion metrics during the rollout.

   • ↳Have a rollback plan ready.
   • ↳Monitor Datadog's own status page for any reported issues.
7. 7

   Full Deployment and Verification

   deploy

   Once confident, deploy the v2 integration across your entire environment. Continue to monitor key metrics and verify that data is being ingested correctly in Datadog.

   • ↳Confirm data in Datadog dashboards match expected values.
   • ↳Inform relevant teams about the migration completion.

Testing Checklist

1. 1.

   Authentication Success

   Send a simple API request and verify a 2xx response code.

2. 2.

   Data Ingestion (Metrics)

   Submit sample metric data and confirm its appearance in Datadog Metrics Explorer.

3. 3.

   Data Ingestion (Logs)

   Send sample log events and verify they are searchable in Datadog Logs.

4. 4.

   Data Ingestion (Traces)

   Submit sample trace data and check its visibility in Datadog APM.

5. 5.

   Error Response Handling

   Simulate invalid requests and verify correct error codes and messages are returned.

6. 6.

   Pagination and Rate Limits

   Test fetching large datasets and monitor responses for rate limit headers.

Common Mistakes