ThisCalculator

Everyday

New Relic CLI: Inspect Telemetry from Terminal

Updated · Standard formula, shown below

New Relic CLI: Inspect Telemetry from Terminal

This guide shows you how to use the New Relic CLI (command-line interface) to inspect application telemetry—metrics, events, logs, and traces—directly from your terminal. You’ll learn how to query your data, view entity summaries, and run NRQL (New Relic Query Language) queries without leaving the command line. This is especially useful for quick debugging, automated scripts, and CI/CD pipelines where a web UI is impractical.

What You’ll Need

  • New Relic account with access to the data you want to inspect (e.g., APM, infrastructure, logs).
  • New Relic User API key (Ingest keys won’t work for querying). Create one in the New Relic UI under Account Settings → API keys → Create key → type: User.
  • New Relic CLI installed. The official CLI is called newrelic. Install via Homebrew (macOS/Linux): brew install newrelic-cli, or download the binary from the official New Relic docs. Verify with newrelic --version.
  • Terminal with network access to New Relic’s APIs.

Step-by-Step

  1. Authenticate the CLI. Run newrelic profile add. It will prompt for your API key and account ID. Alternatively, set environment variables: export NEW_RELIC_API_KEY=your_user_key and export NEW_RELIC_ACCOUNT_ID=your_account_id. You can also use newrelic profile list to see active profiles.
  2. List your applications. To see all APM applications in your account, run newrelic entity search --type APPLICATION. This returns a list of entity GUIDs and names. You’ll need the GUID for targeted queries.
  3. Get a specific entity’s details. Use newrelic entity get --guid <GUID> to view metadata like application name, language, and health status.
  4. Run a basic NRQL query. The core command for telemetry is newrelic nrql query. For example, to get average response time for the last hour: newrelic nrql query --query "SELECT average(duration) FROM Transaction SINCE 1 hour ago". Replace Transaction with your event type (e.g., Log, Metric, Span).
  5. Filter by entity. Add a WHERE clause using the entity GUID: ... WHERE entityGuid = '<GUID>'. For APM, you can also filter by appName.
  6. View raw log data. For logs, query SELECT * FROM Log SINCE 15 minutes ago. The CLI will output JSON. Use --format table (or --format json) to control output. Table format is easier to read for simple queries.
  7. Inspect traces and spans. Query Span events: SELECT * FROM Span SINCE 30 minutes ago WHERE entityGuid = '...'. This shows individual spans with duration, service, and trace ID.
  8. Use time ranges. The CLI supports relative time (e.g., SINCE 1 day ago) and absolute (e.g., SINCE '2025-01-01 00:00:00' UNTIL '2025-01-01 12:00:00'). Always include a time range to avoid querying all data.
  9. Export results to a file. Append --output /path/to/file.json to save the result. This is useful for further processing with jq or other tools.
  10. Check entity health. Use newrelic entity get --guid <GUID> --includeHealth to see if the application is reporting issues.

Common Mistakes

  • Using an Ingest key instead of a User key. Ingest keys are for sending data, not reading it. You’ll get a 403 Forbidden error.
  • Forgetting the time range. NRQL queries without a SINCE/UNTIL clause may fail or return unexpected results. Always specify a time window.
  • Incorrect event type. Typing Transaction when your data is in Log will return no results. Check the event types available via SHOW EVENT TYPES (not directly supported in CLI, but you can query SELECT * FROM NrUsage or use the UI).
  • Not quoting the query. If your query contains spaces or special characters, wrap it in double quotes in the shell.
  • Using the wrong account ID. If you have multiple accounts, ensure your profile points to the correct one.

Tips

  • Use jq to parse JSON output. For complex queries, pipe the JSON to jq: newrelic nrql query --query "..." --format json | jq '.results[0].average'.
  • Create shell aliases. For frequent queries, add aliases like alias nrql='newrelic nrql query --query'.
  • Leverage NRQL facets. Use FACET appName to group results by application. Example: SELECT count(*) FROM Transaction FACET appName SINCE 1 hour ago.
  • Use the --verbose flag to see the exact API request being made, which helps debug.
  • Combine with cron. Schedule NRQL queries to run periodically and send alerts via your own scripts.

Troubleshooting

  • Error: “API key invalid”. Double-check your key is a User key, not an Ingest key. Regenerate if necessary. Also ensure no leading/trailing spaces.
  • Error: “Account not found”. Verify your account ID. Run newrelic profile list to see the configured account.
  • Command not found. Ensure the CLI is installed and in your PATH. Try reinstalling or using the full path.
  • Query returns empty results. Check the time range—maybe no data exists in that window. Also verify the event type and entity GUID are correct. Try a broader query without filters.
  • Output is too large. Use LIMIT 10 in your NRQL query to reduce the result set. The CLI also has a --limit flag for some commands.
  • Rate limiting. If you hit API rate limits, add a delay between requests or use the --timeout flag to increase wait time.

Frequently Asked Questions

Can I query logs with the CLI?

Yes, use NRQL: SELECT * FROM Log SINCE 1 hour ago. You can filter by message or entityGuid.

How do I get the entity GUID?

Run newrelic entity search --type APPLICATION and copy the GUID from the output, or use newrelic entity get --guid ... after finding it.

Can I use the CLI to send telemetry?

Yes, but that’s a different feature. Use newrelic agent or newrelic events post for sending data. This guide focuses on reading.

Does the CLI support NRQL alerts?

Not directly. You can create alerts via the UI or API, but the CLI is mainly for querying. Use newrelic alerts commands for managing alert policies.

Can I export results to CSV?

Currently, the CLI outputs JSON or table format. You can convert JSON to CSV using jq or a tool like csvkit.

Is there a way to watch live telemetry?

You can run a query with SINCE 1 minute ago repeatedly in a loop, but there’s no built-in streaming. For live dashboards, use the New Relic UI.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.