{"id":20195066,"url":"https://github.com/newrelic-experimental/newrelic-java-httpservlet-transaction-namer","last_synced_at":"2026-02-06T02:31:45.517Z","repository":{"id":72141560,"uuid":"285027677","full_name":"newrelic-experimental/newrelic-java-httpservlet-transaction-namer","owner":"newrelic-experimental","description":"A New Relic Java Agent extension to facilitate custom instrumentation to javax.servlet.http.HttpServlet, primarily to rename transactions.","archived":false,"fork":false,"pushed_at":"2024-12-20T09:10:25.000Z","size":403,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-09-21T20:49:58.474Z","etag":null,"topics":["httpservlet","instrumentation","java","namer","naming","nrlabs","nrlabs-data","nrlabs-odp","observability-data","transaction"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/newrelic-experimental.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"cla.md"}},"created_at":"2020-08-04T15:52:16.000Z","updated_at":"2024-12-20T09:10:26.000Z","dependencies_parsed_at":"2023-04-12T07:02:38.723Z","dependency_job_id":"a1b38592-4010-4466-a173-1eeaa1b34bf6","html_url":"https://github.com/newrelic-experimental/newrelic-java-httpservlet-transaction-namer","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/newrelic-experimental/newrelic-java-httpservlet-transaction-namer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/newrelic-experimental","download_url":"https://codeload.github.com/newrelic-experimental/newrelic-java-httpservlet-transaction-namer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29145839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T01:13:33.096Z","status":"online","status_checked_at":"2026-02-06T02:00:08.092Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["httpservlet","instrumentation","java","namer","naming","nrlabs","nrlabs-data","nrlabs-odp","observability-data","transaction"],"created_at":"2024-11-14T04:15:39.012Z","updated_at":"2026-02-06T02:31:45.495Z","avatar_url":"https://github.com/newrelic-experimental.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://opensource.newrelic.com/oss-category/#new-relic-experimental\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/newrelic/opensource-website/raw/main/src/images/categories/dark/Experimental.png\"\u003e\u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Experimental.png\"\u003e\u003cimg alt=\"New Relic Open Source experimental project banner.\" src=\"https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Experimental.png\"\u003e\u003c/picture\u003e\u003c/a\u003e\n\n# New Relic Java Agent - HTTPServlet Transaction Namer\n\nA New Relic Java Agent extension that provides the ability to add custom instrumentation around the J2EE `javax.servlet.http.HttpServlet#service()` method.\n\n**Historical Note:** Historically this extension only provide the naming functionality, which is why the extension is named 'HTTPServlet-transaction-namer'.\n\n## Installation\n\nTo install:\n\n1. Download the latest release jar files.\n2. In the New Relic Java directory (the one containing newrelic.jar), create a directory named extensions if it does not already exist.\n3. Copy the downloaded jars into the extensions directory.\n4. Restart the application.  \n5. Add the appropriate settings to `newrelic.yml` as described in the [Configuration](#configuration) section.\n6. Restart your JVM\n7. After the app has reloaded, generate traffic against your app that will trigger transactions that you expect to see renamed.\n8. To debug issues, set `log_level` to `finer` in `newrelic.yml`.\n\n## Getting Started\n\nBy default, the built-in [`TransactionNamer`](#httpservlet-transaction-namer) instrumentation is registered. This instrumentation can be used to alter the way in which the `Transaction` name is set for a Servlet request.\n\n## Usage\n\n## Configuration\n\nAll configuration of this extension is done in `newrelic.yml` or alternatively, via [java properties](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties).\n\n1. **You must disable auto transaction naming.** Find the parameter called `enable_auto_transaction_naming` and set it to `false`.\n1. Enable the extension you copy the YAML snippet from [the configuration template below](#configuration-template) and paste it within the `common:` section of the `newrelic.yml`. *Note:* It can be anywhere within the common section (for example, below the app_name parameter).\n1. See the [renaming options](#transactionnamer-renaming-options) to determine which to use.\n1. Ensure that the indentation levels of the `httpservlet_transaction_namer` section match exactly to the way they appear in the template below. **Every indentation in YAML is 2 spaces (_NOT_ tabs)**. The `httpservlet_transaction_namer:` line should have exactly 2 spaces in front of it, the next line should have 4, and so on.\n\n\n\n### Configuration Template\n\n```yaml\n  httpservlet_transaction_namer:\n    instrumentations:\n      - com.newrelic.fit.javax.servlet.http.TransactionNamer\n    append_parameters:\n      enabled: true\n      parameters:\n        - name: categoryId\n          type: parameter\n        - name: host\n          type: header\n    name_grouper:\n      enabled: true\n      patterns:\n        - '(\\/wps\\/myportal\\/[^!]*)!ut.*'\n        - '(\\/jpetstore_web\\/[^.]*)\\..*'\n        - '(\\/jpetstore_web\\/accounts\\/)[^\\/]+\\/(.*)'\n    name_obfuscator:\n      enabled: true\n      patterns:\n        - '/AncillaryApplication/\u003crecLoc\u003e/\u003clastName\u003e'\n        - 'AncillaryApplication/\u003crecLoc,\\w{3}\u003e/\u003clastName,\\w+\u003e'\n        - '/Ancillary\\w+/\u003crecLoc,\\w{3}\u003e/\u003clastName\u003e'\n        - '(?\u003cobfuscatedVin\u003e[A-Za-z\\d]{11}\\d{6})'\n```\n\n### Renaming options\n\nBy default, the built-in `TransactionNamer` instrumentation is registered with the extension.  This  instrumentation can be used to alter the way in which the transaction name is set for a Servlet request.  The TransactionNamer provides 3 mechanisms for altering the transaction name:\n\n1. [`append_parameters`](#append-parameters) - Renaming based on HTTP parameters/cookies/headers\n1. [`name_grouper`](#name-grouper) - Grouping transaction names\n1. [`name_obfuscator`](#name-obfuscator) - Obfuscating transaction names\n1. [Custom instrumentation](#custom-instrumentation)\n\n### Append parameters\n\nUse `append_parameters` to rename Transactions using HTTP parameters, cookies \u0026 headers. You can append any HTTP request parameter, cookie or header to the transaction name.\n\n```yaml\n    append_parameters:\n      enabled: true\n      parameters:\n        - name: [parameter_name]\n          type: [cookie|header|parameter]\n        - name: [parameter_name]\n          type: [cookie|header|parameter]\n```\n* Valid values for `transaction_parameter_type` are `cookie`, `header` and `parameter`.\n* You can append as many parameters as you want. Each one gets its own list member (signified by a `-`), name and type.\n* The parameters will be appended in the order in which they are listed.\n\n### Name grouper\n\nUse `name_grouper` to group your transactions into names from URL segments. Using regular expression patterns, choose which URLs to analyise and the segments by which you want to group transations.\n\n```yaml\n    name_grouper:\n      enabled: true\n      patterns:\n        - 'pattern 1'\n        - 'pattern 2'\n        - 'pattern 3'\n```\n\n* The patterns are regex patterns that are matched against the URI.\n* Each pattern must be on it's own line, surrounded by single-quotes.\n* Use normal Java regular expressions as the pattern.\n  * Great tutorial/reference for regex: http://www.regular-expressions.info/\n  * Regex building tool: http://www.regexr.com/\n* For any segment you wish to preserve, use a regex grouping `(like this)`.\n* For any segment you wish to group by, do NOT put it in a regex grouping. It will simply not appear in the resultant transaction name.\n* Each URI will be successfully matched only once - subsequent patterns that would match that URI will not be tested.\n\n#### Example name_grouper patterns\n\n_Pattern 1: Group WebSphere Portal transactions without Stateful URL string_\n\n* Pattern: `(\\/wps\\/myportal\\/[^!]*)!ut.*`\n* Matches the following URLs:\n  * `/wps/myportal/Search/Search%20Center/!ut/p/a1/04_Sj9CPykssy0xPLMnMz0vMAfGjzOKd3R0`\n  * `/wps/myportal/tagging/!ut/p/a1/04_Sj9CPy328dh23ch249fho2ij1jKJ8x9T`\n* Groups these URLs as:\n  * `/wps/myportal/Search/Search%20Center/`\n  * `/wps/myportal/tagging`\n* Does NOT match the following URLs:\n  * `/wps/portal/Search/Search%20Center/!ut/p/a1/04_Sj9CPykssy0xPLMnMz0vMAfGjzOKd3R0`\n  * `/wps/myportal/tagging/some/other/stuff`\n\n_Pattern 2: Strip extensions from URI (.jsp, .html, etc.)_\n\n* Pattern: `(\\/jpetstore_web\\/[^.]*)\\..*`\n* Matches the following URLs:\n  * `/jpetstore_web/catalog/Item.jsp`\n  * `/jpetstore_web/help.html`\n* Groups these URLs as:\n* `/jpetstore_web/catalog/Item`\n* `/jpetstore_web/help`\n* Does NOT match the following URLs:\n  * `/jpetstore_web/catalog/Checkout`\n  * `/jpetstore_notweb/catalog/Item.jsp`\n\n_Pattern 3: Combine transactions from different subdirectories (i.e. per-account settings)_\n\n* Pattern: `(\\/jpetstore_web\\/accounts\\/)[^\\/]+\\/(.*)`\n* Matches the following URLs:\n  * `/jpetstore_web/accounts/account1/editAccount`\n  * `/jpetstore_web/accounts/another_account/doEdit`\n* Groups these URLs as:\n  * `/jpetstore_web/accounts/editAccount`\n  * `/jpetstore_web/accounts/doEdit`\n* Does NOT match the following URLs:\n  * `/jpetstore_web/accounts/noaccount`\n  * `/jpetstore_notweb/accounts/account1/editAccount`\n\n### Name obfuscator\n\nUse `name_obfuscator` to obfuscate URL segments in Transaction Names. Using regular expression patterns, choose which URLs to analyise and which segments will be masked AND grouped together.\n\n```yaml\n    name_obfuscator:\n      enabled: true\n      patterns:\n        - 'pattern 1'\n        - 'pattern 2'\n        - 'pattern 3'\n```\n\n* For any segment you wish to obfuscate, use `\u003creplacement_name\u003e`, in which `replacement_name` is the name you want to group that segment as, for example `\u003clastName\u003e`.\n* For any segment you wish to obfuscate AND it requires a regex statement to collect, use the following notation:\n`\u003creplacement_name,regex\u003e`.\n* Each pattern must be on it's own line, surrounded by single-quotes.\n* You can use normal Java regular expressions anywhere in the pattern, even outside of obfuscated fields.\n  * Great tutorial/reference for regex: http://www.regular-expressions.info/\n  * Regex building tool: http://www.regexr.com/\n\n#### Example name_obfuscator patterns\n\n_Pattern 1: Basic pattern match using \u003creplacement_name\u003e notation in URL pattern_\n\n* Pattern: `'/AncillaryApplication/\u003crecLoc\u003e/\u003clastName\u003e'`\n* Matches the following URLs:\n  * `/AncillaryApplication/92Jets/Selanne`\n  * `/AncillaryApplication/Helsinki/Kurri17`\n* Groups these URLs as:\n  `/AncillaryApplication/\u003crecLoc\u003e/\u003clastName\u003e`\n* Does NOT match the following URLs:\n  * `/AncillaryApplication/92Jets/Selanne/Teemu`\n  * `/NotAncillaryApplication/Turku/Koivu`\n\n_Pattern 2: Using \u003creplacement_name,regex\u003e notation in URL pattern_\n\n* Pattern: `'AncillaryApplication/\u003crecLoc,\\w{3}\u003e/\u003clastName,\\w+\u003e'`\n* Matches the following URLs:\n  * `/AncillaryApplication/HEL/Kapanen`\n  * `/AncillaryApplication/KUO/Timonen`\n* Groups these URLs as:\n  `/AncillaryApplication/\u003crecLoc\u003e/\u003clastName\u003e`\n* Does NOT match the following URLs:\n  * `/AncillaryApplication/Helsinki/Tikkanen`\n  * `/AncillaryApplication/OUL/Pitkanen25`\n\n_Pattern 3: Using regex elsewhere in URL pattern_\n\n* Pattern: `'/Ancillary\\w+/\u003crecLoc,\\w{3}\u003e/\u003clastName\u003e'`\n* Matches the following URLs:\n  * `/AncillaryApplication/TMP/Numminen` grouped as `/AncillaryApplication/\u003crecLoc\u003e/\u003clastName\u003e`\n  * `/AncillaryApp/TKU/Salo` grouped as `/AncillaryApp/\u003crecLoc\u003e/\u003clastName\u003e`\n\n_Pattern 4: Replace regex pattern everywhere in URL path_\n\n* Pattern: `'(?\u003cobfuscatedVin\u003e[A-Za-z\\d]{11}\\d{6})'`\n* Matches the following URLs:\n  * `/VehicleApplication/AB1CDE2EFGH567890` grouped as `/VehicleApplication/\u003cobfuscatedVin\u003e`\n  * `/VehicleApplication/AB1CDE2EFGH567890/AnotherSegment/IJ1KLM2NOPQ567890/TheEnd` grouped as `/VehicleApplication/\u003cobfuscatedVin\u003e/AnotherSegment/\u003cobfuscatedVin\u003e/TheEnd`\n\n#### Excluding request.uri attribute \n\nThe most recent Java agent versions have introduced constraints on altering agent attributes. This makes it necessary to exclude the \"request.uri\" attribute and utilize the obfuscated \"custom.request.uri\" instead. To apply this change, navigate to the newrelic.yml file, locate the \"attributes\" section, and modify the \"exclude\" parameter as described below:\n\n```yaml\n # Provides the ability to configure the attributes sent to New Relic. These\n # attributes can be found in transaction traces, traced errors,\n # transaction events, and page views.\n attributes:\n\n  # When true, attributes will be sent to New Relic. The default is true.\n  enabled: true \n  #A comma separated list of attribute keys whose values should\n  # be sent to New Relic.\n  #include: \n\n  # A comma separated list of attribute keys whose values should\n  # not be sent to New Relic.\n  exclude: request.uri\n```\n\n### Custom instrumentation\n\nAdditional custom instrumentations can be created as follows.\n\n1. Create a class that implements the `ServletInstrumentation` interface.  The\nJavadoc for this interface is included with the distribution package.\n    1. Implement the `init(Config config)` method.  This method is called only once\n    throughout the lifetime of the parent class loader.  Use this time to initialize\n    any private variables based on the Agent configuration in `config`.\n    1. Implement the `instrumentRequest(request, response, agent, config)` method.\n    This method is called once for every servlet request.  Logic contained in this\n    method should consume as few compute resources as possible since it is called\n    frequently.\n1. Ensure that the compiled class file for you class is present on the\napplication server `CLASSPATH`.  Mechanisms for this vary and are outside the\nscope of this documentation.\n1. Register the custom instrumentation by updating the New Relic Java agent\nconfiguration (newrelic.yml) as follows.\n    1. Locate the `custom.httpservlet_transaction_namer.instrumentations` property\n    in the YML.\n    1. Add a new line with proper indentation that contains the ` - ` prefix and\n    the fully-qualified class name of the custom class.  E.g.\n        ```yaml\n        httpservlet_transaction_namer:\n          instrumentations:\n           - com.newrelic.fit.javax.servlet.http.TransactionNamer\n           - path.to.my.package.CustomInstrumentation\n        ```\n    1. Add any other configuration necessary for the custom instrumentation within\n    the `httpservlet_transaction_namer` container in the YAML.  E.g.\n        ```yaml\n        httpservlet_transaction_namer:\n        ...\n          my_custom_stuff:\n            foo: bar\n            list:\n             - 1\n             - 2\n        ```\n    The custom instrumentation can access this data through the `config` parameter\n    in the `init(config)` method.\n1. Restart your JVM and your extension should be available.\n\n## Building\n\nIf you make changes to the instrumentation code and need to build the instrumentation jars, follow these steps\n1. Set environment variable NEW_RELIC_EXTENSIONS_DIR.  Its value should be the directory where you want to build the jars (i.e. the extensions directory of the Java Agent).   \n2. Build one or all of the jars.   \na. To build one jar, run the command:  gradlew httpservlet-transaction-namer:clean httpservlet-transaction-namer:install   \nb. To build all jars, run the command: gradlew clean install\n3. Restart the application\n\n## Testing\n\nThere is a `test` gradle target defined for this project that runs JUnit tests.\n\n## Support\n\nNew Relic has open-sourced this project. This project is provided AS-IS WITHOUT WARRANTY OR DEDICATED SUPPORT. Issues and contributions should be reported to the project here on GitHub. We encourage you to bring your experiences and questions to the [Explorers Hub](https://discuss.newrelic.com) where our community members collaborate on solutions and new ideas.\n\n## Contributing\n\nWe encourage your contributions to improve HTTPServlet Transaction Namer! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.\nIf you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company,  please drop us an email at opensource@newrelic.com.\n\n**A note about vulnerabilities**\n\nAs noted in our [security policy](../../security/policy), New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.\n\nIf you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through [HackerOne](https://hackerone.com/newrelic).\n\n## License\n\nHTTPServlet Transaction Namer is licensed under the [Apache 2.0](http://apache.org/licenses/LICENSE-2.0.txt) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnewrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewrelic-experimental%2Fnewrelic-java-httpservlet-transaction-namer/lists"}