monitoring with ngrok and datadog #1272
Conversation
Edit: Monitor ngrok APIs with Datadog
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Updates Monitoring ngrok
Edit: Observe your API traffic with ngrok and Datadog
Update Monitoring ngrok
There was a problem hiding this comment.
Leaving some feedback here to start with! I wanted to start with some overall change in direction, mostly based on a few questions I had and to make this read as an actual follow-on to the API gateway guides we already have.
I really love the What to monitor? section! And as a whole, this fills a huge gap in our docs/how-tos in how to actually use all the observability tools in ngrok.
Some other things:
- We should move this from
/docs/guides/other-guides/to/docs/guides/api-gateway/to make the movement from API gateway guides into this more "official." - I need to go through this with more detail in another pass, but overall the prose feels good.
- I'm going back and forth on whether we should keep the steps as bulleted lists. It works well with highly specific processes that a user needs to follow, like setting up Datadog, but doesn't align perfectly with some of our recent guides.
- We need to remove the changes to
pnpm.lockto merge this.
|
|
||
| This guide explains how to monitor your API or web app with ngrok by viewing traffic reports, using error request replays, and exporting logs and events to an external dashboard. | ||
|
|
||
| Whether you're an existing ngrok user looking to make your API more robust or a new user wondering whether ngrok meets your needs, this tutorial will demonstrate monitoring in detail. |
There was a problem hiding this comment.
I don't think this is necessary—we can cut.
| ## Start the sample API to monitor | ||
|
|
||
| Let's start the sample API. Open a terminal and run the commands below. | ||
|
|
||
| ```sh | ||
| docker network create ngrokTest | ||
|
|
||
| docker run --init --platform=linux/amd64 --rm -p 4000:80 --network=ngrokTest --name="api" -e PORT=80 joelatngrok/api-demo | ||
| ``` | ||
|
|
||
| This command runs the Docker sample API container, exposing the API locally on port 4000, names the Docker container `api`, and removes the container with `--rm` upon exiting. You can now browse to http://localhost:4000 to test the API. | ||
|
|
||
| :::note | ||
| The API uses a named network, `ngrokTest`, so that in the next section, you can start the ngrok Agent on the same network as the API. | ||
| ::: | ||
|
|
||
|  | ||
|
|
||
| ## Publish your API with ngrok | ||
|
|
||
| Now that the API is running locally, you can expose it on a public URL, using the [Docker image for the ngrok agent](https://hub.docker.com/r/ngrok/ngrok). | ||
|
|
||
| - Replace the authentication token in the command below with your token from the [ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken), and run the command in a new terminal. | ||
|
|
||
| ```sh | ||
| docker run -it --rm --platform=linux/amd64 --network=ngrokTest -e NGROK_AUTHTOKEN=Y0urS3cr3tK3y ngrok/ngrok:3.22.0-alpine-amd64 http http://api | ||
| ``` | ||
|
|
||
| This command starts the ngrok agent locally and connects it to the API running on the `api` container. | ||
|
|
||
| - Browse to the URL labeled `Forwarding`, which should look like this in your terminal: `https://eb45-79-127-145-72.ngrok-free.app`. | ||
| - You can now see your request going from the browser to the ngrok agent you're running in one terminal window and then to the API in your other terminal window. | ||
|
|
||
|  |
There was a problem hiding this comment.
What I'd prefer to do here is cut all this and instead use the change I requested above, which points folks to the previous API gateway guides, so that they already have the API demo app running and their whole API gateway configured.
| - The [ngrok Agent Endpoints](https://ngrok.com/docs/universal-gateway/agent-endpoints) documentation | ||
| - The [ngrok Events](https://ngrok.com/docs/obs/events) documentation | ||
| - [Datadog](https://www.datadoghq.com) | ||
| - [ntfy](https://ntfy.sh) |
There was a problem hiding this comment.
Not sure why this link is here.
docs/obs/traffic-inspection.mdx
Outdated
| @@ -48,6 +48,12 @@ Once Full Capture is enabled, a replay button will appear for fully captured req | |||
|
|
|||
| Replay works by resending your original unmodified request to your endpoint. It will be subject to the policies of that endpoint at the time of replay (which could be different than the original request). | |||
|
|
|||
| :::warning | |||
|
|
|||
| You need to use a permanent endpoint for your service for replay to work. If you are using a free ngrok account, where the URL changes every time you restart the agent, the replay request will fail as it tries to contact an endpoint that no longer exists. | |||
There was a problem hiding this comment.
Isn't this only true if you've stopped or restarted your agent since the request was logged in Traffic Inspector?
|
|
||
| - Sign up for a [Datadog](https://www.datadoghq.com) trial account. (You will eventually need a paid Datadog plan to continue using logs and monitors.) | ||
|
|
||
| You can enter anonymous dummy values instead of your personal information for all the Datadog registration fields except your email address, which you need to confirm. You also can't skip the third step of the sign-up process, in which you create a Datadog agent somewhere. |
There was a problem hiding this comment.
I don't love this tip of using dummy values—feels incongruous with our target ICP here, who are more DevOps/infra engineers with production API gateways.
| - In Step 3 of the Datadog sign-up, click on **Docker** in the sidebar. Copy and paste the given command into a terminal and run it. | ||
|
|
||
|  | ||
|
|
||
| - Once the Datadog site notices your agent is running, click **Finish** at the bottom of the page. | ||
| - You now no longer need the agent running locally and can remove the Datadog container with the command below. | ||
|
|
||
| ```sh | ||
| docker stop dd-agent | ||
| docker remove dd-agent | ||
| docker image rm gcr.io/datadoghq/agent:7 | ||
| ``` |
There was a problem hiding this comment.
Can you get an API key this way? https://docs.datadoghq.com/account_management/api-app-keys/#add-an-api-key-or-client-token
|
Also flipping this over to ready to be reviewed to we can get CI running on it and look at deploy previews. |
Co-authored-by: Joel Hans <[email protected]>
# Conflicts: # docs/guides/api-gateway/get-started.mdx # docs/guides/api-gateway/kubernetes.mdx # docs/guides/api-gateway/multicloud.mdx
feedback updates Monitoring ngrok
|
Hi! I'm I would like to apply some automated changes to this pull request, but it looks like I don't have the necessary permissions to do so. To get this pull request into a mergeable state, please do one of the following two things:
|
autofix.ci
|
Hey @sixhobbits! Could you enable the allow edits by maintainers option for this? https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork#enabling-repository-maintainer-permissions-on-existing-pull-requests |
|
Closing in favor if #1351—thank you @sixhobbits and team for carrying it this far! |
For @joelhans