Observability in the IDE with CodeStream

New Relic CodeStream allows developers to see how the code they're responsible for is performing in production by bringing observability into the IDE and making it part of their daily routine.

Connect CodeStream and New Relic

To access observability in your IDE you'll need to connect CodeStream to New Relic via your New Relic user API key (learn more about New Relic user API keys).

Once you have your user API key, click Connect to New Relic in the Observability section of CodeStream, then paste your user API key and click Connect to New Relic. If you signed up for CodeStream using your New Relic user API key then you'll already be connected.

To use the observability features in CodeStream, note that you must have a New Relic user type of core user or full platform user.

Associate repositories with New Relic entities

The telemetry data available in CodeStream is contextual, meaning that it's all related to the code you have open in your IDE. To do this, CodeStream needs to know what entities in New Relic are built by the repositories you have open, and there are a number of ways to make these associations.

There are instances where CodeStream will prompt you to make an association if one doesn't exist. For example, if you try to view an error from New Relic in CodeStream, and the entity the error belongs to isn't associated with a repository, CodeStream will ask you to identify the appropriate repository. The Observability section of the the CodeStream pane will also prompt you to make an association for the currently selected repository in your IDE.

In some cases your repository may need to be associated with multiple entities. For example, you might have different entities that represent different environments (like production, or staging) and they may all be associated with the same repository. To associate the current repository with an additional entity, click on Add another service.

Making these associations on the fly when prompted is a great way to get started, but we recommend one of the following methods because they require less ongoing manual effort and eliminate the possibility of end-user mistakes, such as misconfigured remote URLs.

Use environment variable with APM (recommended)

Set the environment variable NEW_RELIC_METADATA_REPOSITORY_URL. New Relic APM agents create the repository entity and associate it with your application entity automatically.

This requires the SSH or HTTPS remote URL format. We recommend that this be set as part of your build pipeline.

Use the UI

After you've started sending data to New Relic, use the UI to connect your related repository. Go to the APM summary page via one.newrelic.com > All capabilities > APM & Services > (select an app), then look for the Repositories section on the bottom-right.

Click Connect repository to find an existing repository or add a new one.

Use the NerdGraph API

Use New Relic's NerdGraph APIs to create a repository and associate it with your application entities.

Step 1: Create a repository entity

To create a repository entity, use the referenceEntityCreateOrUpdateRepository API and make sure to save the GUID that's produced. The API takes the following parameters:

• accountId - the integer account ID for the account you want to add the repository to

• url - example https://github.com/newrelic/beta-docs-site.git

• name - example: newrelic/beta-docs-site

  mutation {
    referenceEntityCreateOrUpdateRepository(
      repositories: [
        { accountId: [YOUR_ACCOUNT_ID], name: "[REPO_NAME]", url: "[REPO_URL]" }
      ]
    ) {
      created
      failures {
        guid
        message
        type
      }
    }
  }

  Copy

  To find the entity you create, you can use a query like the following. Note that the URL you provided to referenceEntityCreateOrUpdateRepository gets saved as an entity tag.

  {
    actor {
      entitySearch(query: "name = 'a name' OR tags.url = 'a url'") {
        count
        query
        results {
          entities {
            guid
            name
            tags {
              key
              values
            }
          }
        }
      }
    }
  }

  Copy

  Step 2: Associate the repository entity to your application entity

  First, find the GUID for the application you want to associate your repository to.

  Parameters:

• sourceEntityGuid - the entity GUID of the application

• targetEntityGuid - the entity GUID of your repository

• type - always BUILT_FROM

  mutation {
    entityRelationshipUserDefinedCreateOrReplace(
      sourceEntityGuid: ""
      targetEntityGuid: ""
      type: BUILT_FROM
    ) {
      errors {
        message
        type
      }
    }
  }

  Copy

  To see all entities related to your repository you can do a query like this:

  {
    actor {
      entity(guid: "[YOUR_REPOSITORY_GUID]]") {
        relatedEntities(
          filter: { direction: BOTH, relationshipTypes: { include: BUILT_FROM } }
        ) {
          results {
            target {
              entity {
                name
                guid
                type
              }
            }
            type
          }
        }
        name
        type
        tags {
          values
          key
        }
      }
    }
  }

  Copy

  Step 3: Cleanup (if needed)

  Delete a repository with the following query:

  mutation DeleteRepository {
    entityDelete(guids: "[ENTITY_GUID_HERE]]") {
      deletedEntities
      failures {
        message
        guid
      }
    }
  }

  Copy

With any of these methods you can specify the remote URL in either the SSH or HTTPS format:

• git@github.com:newrelic/beta-docs-site.git
• https://github.com/newrelic/beta-docs-site.git

Observability in the IDE

The Observability section of CodeStream gives developers a view into how their code is performing by allowing them to see golden metrics and errors for each service associated with the repository currently selected in the IDE. Each service has its own node in the tree, and when expanded it shows the service's golden metrics, service level objectives, errors assigned to you, and the five most recent errors. You can also see the bigger picture by digging into the services that are called by or call your service, and see the golden metrics for each of them.

If the currently selected repository isn't associated with a service on New Relic you'll be prompted to make the association, or instrument the project.

When hovering over a service name in the tree, click on the globe to open the service's summary page in New Relic. Click on any error to view the details, including the stack trace, and start collaborating on resolution.

Code-level metrics

Code-level metrics give you detailed insight into how your code is performing at the method level. Metrics are displayed right in the editor above instrumented methods, allowing performance data to influence the work at hand. CodeStream will also identify poorly performing methods in your code, allowing you to proactively address performance issues as they arise.

In-editor performance data

Without having to seek it out, performance data is displayed contextually in the editor so that it can inform the work at hand. Say you’re working on a bug fix, and happen to notice that the area of the code you’re working in has an elevated error rate. Maybe you address that issue as part of your bug fix so that it doesn’t escalate into a bigger problem.

CodeStream will show the average duration and error rate, for the last 30 minutes, in a CodeLens above each method instrumented by the New Relic APM agents. Metrics are calculated for the service currently selected in the Observability section of CodeStream. Expand a different service and the metrics will update accordingly.

Click the CodeLens to see charts visualizing each of the metrics. If the repository is associated with multiple New Relic-monitored services, you can easily switch between them. This will change the service upon which the code-level metrics displayed in both the charts and the editor are based, and also change the service selection in the Observability section.

Along with a chart of the error rate you’ll also see a list of the actual errors happening in the same timeframe, including the number of occurrences for each. If the error rate is spiking, and you see one particular error is causing the problem, you can click on it to view the stack trace and start collaborating on resolution.

Anomaly detection

CodeLenses are great for when you happen to be working in a section of the code exhibiting a performance problem, but performance issues are too important to just stumble upon! CodeStream will automatically call out poorly performing methods in your code in the Observability > Code-Level Metrics section.

CodeStream identifies these methods by looking for anomalies in either error rate or average duration. If you’re using New Relic’s change tracking to send deployment information, anomalies are calculated by comparing the performance since your last release against the preceding three weeks. Otherwise, we use the last seven days. You can control these timeframes, as well as the thresholds for determining whether or not a given method is performing poorly, by hovering over the Code-Level Metrics heading and clicking on the gear icon.

In addition to the Code-Level Metrics section, CodeStream will also let you know about poorly performing methods via desktop notifications in either VS Code or JetBrains IDEs.

Requirements

In-editor CodeLenses are available for all of New Relic’s APM languages. Anomaly detection, however, is currently only available for Java, .NET, Python and Ruby.

To see metrics, your service must meet the requirements listed below, and the service should have collected data in the last 30 minutes. The New Relic agent attempts to automatically collect data for functions on classes that are tied to HTTP requests. In many cases, and with many frameworks that use an MVC framework, these are often methods on a Controller class.

Because all requests by the New Relic agent are not collected all the time, it’s possible that low-traffic methods will not see any data. If data is missing for a specific method that you wish to see results for, you can use custom instrumentation to fill any gaps. See guidance for Java, .NET, PHP, Python, Ruby, Go and Node.js. Also note that for Node.js, code-level metrics are not captured for anonymous functions.

• Distributed tracing must be enabled. Distributed tracing is on by default in recent versions of all agents, so you only need to worry about this if you've disabled distributed tracing.
• Go: Requires Go agent version 3.24.0 or higher. If you're using VS Code, you must also have the Go for VS Code extension installed with the language server enabled.
• Java: Requires Java agent version 7.11.0 or higher. Code-level metrics are only available for projects implemented with a supported Java framework. If you're using VS Code, you must also have the Language Support for Java by Red Hat extension installed. Note that Kotlin support is only available in IntelliJ.
• .NET: Requires .NET agent version 10.2.0 or higher. If you're using Visual Studio, make sure that you have CodeLenses enabled in by going to Tools > Options > Text Editor > All Languages > CodeLens and making sure that both "Enable CodeLens" and "Show CodeStream Code-Level Metrics" are checked. If you're using VS Code, you must have the C# extension installed.
• Node.js: Requires Node.js agent version 10.5.0 or higher.
• PHP: Requires PHP agent version 10.6.0 or higher.
• Python: Requires Python agent version 7.10.0.175 or higher. Code-level metrics are only available for projects implemented with a supported Python framework and for PHP version 7.0 or higher. If you're using VS Code, you must also have the Python extension installed with the language server enabled.
• Ruby: Requires Ruby agent version 8.10.0 or higher. Code-level metrics are only available for Rails applications and Ruby methods with manual traces (learn more about Ruby methods and CodeStream). If you're using VS Code, you must also have either the Ruby or Ruby Solargraph extension installed with the language server enabled.

You can turn CodeLenses off by going to the CodeStream section of your IDE's settings and unchecking the CodeStream: Show Golden Signals In Editor setting.

Investigating errors

CodeStream will show you recent errors happening in the code you have open in your IDE, but you can see a more comprehensive list of APM errors via the errors inbox on New Relic. When you're ready to dig into the root cause of a specific error with a stack trace, click Open in IDE to go directly to the code in your IDE.

Collaborate on resolution

A typical collaboration session could include developers commenting on code in their IDEs, a DevOps engineer assigning errors in errors inbox, and a development manager following along in Slack. By meeting people in the tools they're already using, CodeStream shortens the amount of time between error discovery and error resolution.

Watch this short YouTube video (approx. 2:27 minutes) to see this in action.

Whether you clicked on an error in the Observability section or clicked Open in IDE from the errors inbox on New Relic, CodeStream presents all of the error's details, including the stack trace.

Click any frame in the stack trace to jump straight to the corresponding file and line number in your IDE. Note that frames of the stack trace that represent code that isn't part of your repository (e.g., an external library) aren't clickable.

As you navigate the stack trace, if you come across code that seems like the source of your problem, select it and click the comment icon to start a discussion. CodeStream automatically mentions the most recent person to touch that code, making it easy for you to bring the right people into the discussion.

Once you've identified the problem you can assign the error, or update the error status from unresolved to resolved or ignored.

Associate build SHAs or release tags with errors

When viewing and error in CodeStream you may see this warning if there's no git reference, either a build SHA or release tag, associated with the error. CodeStream uses the git reference to match the specific stack trace error with the version of the code running in the environment that triggered the error.

While you don't need a git reference configured to investigate the error, bear in mind that you may not be looking at the version of the code that caused it.

You can use an environment variable to let the New Relic APM agent know the commit sha associated with each build of your project. You can also use the release tag associated with the running version of your software.

For New Relic APM, the commit sha and/or release tag (tags.commit and tags.releaseTag) are added as attributes on Transaction and TransactionError events. You can use APM environment variables to set these attributes.

We recommend setting one or both of these variables as part of your build pipeline.

• NEW_RELIC_METADATA_COMMIT - The commit sha. You can include the whole thing or only the first seven characters (e.g., 734713b).
• NEW_RELIC_METADATA_RELEASE_TAG - A release tag (such as v0.1.209 or release-209). This has the advantage of being human readable.

For more on how to set these variables, here are specific configuration details for each language:

• Go
• Java
• .NET
• Node.js
• PHP
• Python

If you do have git references configured, CodeStream will let you know if the version of the code you're on locally doesn't contain the reference associated with the error. In this case, you may want to check out the version of the code that does contain that reference so that you can more effectively investigate and resolve the error.

CodeStream will also let you know if the error doesn't have a stack trace associated with it. This happens with older errors when the stack trace has aged out on New Relic.