Entity Usage
Track usage of entities referenced by other entities in Drupal, showing where content is being used across your site.
entity_usage
Overview
Entity Usage is a powerful module that tracks and displays relationships between entities in Drupal. It monitors how entities reference each other through various field types and embedding methods, then provides reports showing where each entity is being used.
The module automatically tracks when source entities are created, updated, or deleted, maintaining an accurate record of all entity relationships. Users can view a 'Usage' tab on entity pages to see which other entities reference the current entity, with information about the referencing entity type, field name, language, publication status, and revision context.
Entity Usage supports multiple tracking methods including entity reference fields, link fields, HTML links in text fields, media embeds, Layout Builder components, and integrations with contributed modules like Entity Embed, LinkIt, Block Field, and Dynamic Entity Reference. Site administrators can configure which entity types to track as sources and targets, enable/disable specific tracking plugins, and control warning messages shown when editing or deleting entities that are being referenced elsewhere.
Features
- Tracks relationships between entities through entity_reference, entity_reference_revisions, file, image, and webform fields
- Tracks entities referenced via Link fields pointing to internal entity URLs
- Detects and tracks standard HTML links in formatted text fields that point to entity URLs
- Tracks media entities embedded using Drupal core's media embed filter in WYSIWYG editors
- Tracks entities embedded using the Entity Embed contributed module
- Tracks entities linked using the LinkIt contributed module in WYSIWYG editors
- Tracks file entities embedded via CKEditor Image widget
- Tracks entities referenced in Layout Builder layouts including inline content blocks, reusable blocks, and Entity Browser Block selections
- Supports Block Field module for tracking blocks referenced in block_field fields
- Supports Dynamic Entity Reference module for tracking references to multiple entity types
- Provides configurable 'Usage' tab (local task) on entity canonical or edit pages showing all references to that entity
- Displays warning messages on edit forms when an entity has active references elsewhere
- Displays warning messages on delete forms when an entity is being used by other content
- Batch update tool to regenerate all usage statistics for existing content
- Drush command for batch recreation of usage statistics
- Configurable source and target entity type filtering to control what gets tracked
- Support for tracking base fields in addition to configurable fields
- Domain configuration for tracking absolute URLs pointing to the site
- Revision-aware tracking showing usage in default, pending, and old revisions
- Translation-aware tracking with language information displayed
- Integration with Trash module to show trashed source entities appropriately
- Extensible plugin system allowing custom tracking methods to be added
Use Cases
Preventing broken references when deleting content
Enable delete warning messages for content types like Media, Taxonomy Terms, or custom entities. When an editor tries to delete an entity, they'll see a warning showing where it's currently being used, helping prevent broken references across the site.
Auditing media usage across the site
Use the Usage tab on media entities to see everywhere a particular image, video, or document is being used. This helps identify orphaned media files, understand content dependencies, and plan content updates that affect multiple pages.
Managing content dependencies during migrations
Before migrating or restructuring content, use Entity Usage to understand relationship dependencies. This helps plan migration order and identify content that needs special handling due to cross-references.
Tracking where reusable content blocks appear
For reusable block_content entities used across multiple pages via Layout Builder or Block Field, the Usage tab shows every page where the block appears. This is valuable when updating shared content.
Finding all pages linking to a specific internal page
The HTML link tracking plugin detects standard links in WYSIWYG content. Combined with the Usage tab, editors can find every page that links to a specific piece of content, useful for link audits and content restructuring.
Coordinating content updates across translations
Usage listings show the language context of references. When updating multilingual content, editors can see which translations reference an entity and coordinate updates accordingly.
Identifying content referenced only in old revisions
The 'Used in' column distinguishes between default revisions, pending drafts, and old revisions. This helps identify when content is no longer actively used but may still exist in revision history.
Tips
- Run the batch update after initial installation to populate usage data for existing content
- Enable warning messages gradually, starting with the most critical content types to avoid overwhelming editors
- Configure site domains if your content contains absolute URLs - this enables tracking for links that include the full domain
- Use the Drush command for batch updates on large sites to avoid browser timeouts
- The module tracks all revisions and translations - usage data reflects the complete history of references
- Custom tracking plugins can be created by implementing EntityUsageTrackInterface for specialized reference types
- Usage data is automatically cleaned up when source or target entities are deleted
- The hook_entity_usage_block_tracking hook allows fine-grained control over what gets tracked
Technical Details
Admin Pages 3
/admin/config/entity-usage/settings
Configure entity usage tracking settings including which entity types to track, which tracking plugins to enable, and display options for usage information.
/admin/config/entity-usage/batch-update
Delete and regenerate all entity usage statistics. Use this after initial installation or when tracking configuration has changed significantly.
/admin/content/entity-usage/{entity_type}/{entity_id}
Displays a table of all entities that reference the specified target entity. Shows the referencing entity, its type and bundle, language, field name, publication status, and revision context (default, pending, or old revision).
Permissions 3
Hooks 1
hook_entity_usage_block_tracking
Allows modules to block specific usage tracking records from being written to the database. Return TRUE to prevent the record from being saved.
Drush Commands 1
drush entity-usage:recreate
Recreate all entity usage statistics by processing all configured source entity types and regenerating their usage records.
Troubleshooting 7
Navigate to Entity Usage Settings and ensure the entity type is selected under 'Enabled local tasks'. After saving, routes will be rebuilt. Clear caches if the tab still doesn't appear.
Entity Usage only tracks changes made after the module is installed. Run the batch update at /admin/config/entity-usage/batch-update to scan all existing content and populate usage data.
Check Entity Usage Settings to ensure the appropriate tracking plugin is enabled. Also verify that both the source and target entity types are enabled in the respective configuration sections.
Configure the 'Domains for this website' setting with all domains where your site is accessible. Include variations like www and non-www versions, and any staging domains.
The usage database may be out of sync. Run the batch update with existing records deleted to regenerate fresh usage data from current content.
Ensure the entity type is enabled under 'Warning message on edit form' or 'Warning message on delete form' in settings. The entity must also be enabled as a target entity type.
The batch update process is optimized for large sites but may take time. Run via Drush (drush entity-usage:recreate) for better performance and to avoid browser timeouts.