How to Migrate from SentryLogging to Vets::SharedLogging

Last Updated: 02 Sep 2025

This guide walks through migrating logging implementation from the deprecated SentryLogging module to the new Vets::SharedLogging module in Vets API. After completing this migration, you'll be able to control whether your logs go to Sentry, Rails, or both, and your code will be compatible with the eventual removal of SentryLogging.

Before you begin

Before starting this migration, ensure you:

• Have reviewed the SharedLogging introduction PR #21130 to see how Vets::SharedLogging was implemented.

• Can test your changes in a development environment

Step-by-step guide

Step 1: Choose your logging strategy

Decide how you want to handle logging going forward. Sentry will be deprecated in the future (although there’s no date, yet), so we recommend moving away from Sentry logging. There are three options:

Option A: Log to Rails only

• Use Vets::SharedLogging’s log_message_to_rails and log_exception_to_rails

• Or, use Rails.logger. See Rails docs for more info.

• Remove any Sentry logging calls

Option B: Log to both Sentry and Rails (most similar to old SentryLogging behavior)

• Use log_message_to_sentry for Sentry

• Add log_message_to_rails for Rails logging

Option C: Log to Sentry only (Not Recommended)

• Use only log_message_to_sentry and log_exception_to_sentry

Step 2: Identify all uses of SentryLogging in your code

Search vets-api to find all instances where SentryLogging is being used in files owned by your team. Grep command for your convenience:

grep -r "include SentryLogging\|extend SentryLogging\|SentryLogging\." .

Step 3: Update module includes and requires & logging method calls

Replace SentryLogging references with Vets::SharedLogging in each file identified in Step 2.

For instance methods (using include):

1. Add the require statement at the top of your file

2. Replace include SentryLogging with include Vets::SharedLogging

Example of an instance method using both Sentry and Rails logging:

For class methods (using extend):

1. Add the require statement at the top of your file

2. Replace extend SentryLogging with extend Vets::SharedLogging

Example of a class method using both Sentry and Rails logging:

Update your logging calls. See the following examples for message and exception logging:

New SharedLogging Option A (Rails only):

log_message_to_rails("User login failed", :error, { user_id: 123 })
log_exception_to_rails(exception, :error)

# Or use the Rails Logger class
Rails.logger.warn('Service tag missing', class: self.class.name)
Rails.logger.error('[SignIn][AudienceValidator] Invalid audience')

New SharedLogging Option B (both Sentry and Rails):

log_message_to_sentry("User login failed", :error, { user_id: 123 }, { action: "login" })
log_message_to_rails("User login failed", :error, { user_id: 123 })

log_exception_to_sentry(exception, { context: "api_call" }, { service: "external" }, :error)
log_exception_to_rails(exception, :error)

New SharedLogging Option C (Sentry only):

log_message_to_sentry("User login failed", :error, { user_id: 123 }, { action: "login" })
log_exception_to_sentry(exception, { context: "api_call" }, { service: "external" }, :error)

Step 4: Test your changes

Verify that your logging is working correctly in your development environment.

1. Run your application locally

2. Trigger the code paths that contain logging

3. Check that logs appear in the expected locations:

   • For Rails logs: Check log/development.log

4. Run your test suite to ensure no breaking changes.

Step 5: Deploy and monitor

After testing locally:

1. Merge your PR so your changes deploy to the staging environment

2. Monitor logs to ensure they're appearing correctly

3. The deprecation warning (WARNING: This module is deprecated, and will be removed in October 2025. Please use Vets::SharedLogging instead.) should not be in your logs anymore.

4. For Sentry: Check Sentry in staging

5. Check DataDog for logs

Key Differences from SentryLogging

1. Rails logging is explicit - You must call separate methods for Rails logging

2. Tags context - Only available for Sentry methods (log_*_to_sentry); example

3. Exception handling - Rails exception logging is simplified (no extra context parameter)

Next steps

• Update any team documentation to reflect your chosen logging strategy

• If you chose the option to log to Sentry only, please reach out to #platform-cop-backend and let us know your use case. As we move further from Sentry in favor of Datadog, we want to know any use cases for preferring Sentry so we can try to accommodate those in Datadog.

Extras

If you’d like, copy the Markdown below and use in a user story or your pull request.

## User Story
As an engineer working in vets-api, I want to replace `SentryLogging` in anticipation of its deprecation in Oct 2025.

## Tasks
- [ ] Review an example migration PR https://github.com/department-of-veterans-affairs/vets-api/pull/23059
- [ ] Choose logging strategy (Rails only, Sentry & Rails, or Sentry only–not recommended)
- [ ] Identify all team-owned files using `SentryLogging`
- [ ] Update all `SentryLogging` to `Vets::SharedLogging`
- [ ] Test locally
- [ ] PR reviewed and merged
- [ ] Test in staging environment
- [ ] Update team documentation (if needed)

Need help?

If you encounter issues during migration:

• Review the SharedLogging source code

• Check existing implementations using grep -r "Vets::SharedLogging" .

• Reach out in the #vfs-platform-support Slack channel

Help and feedback

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.