In this chapter, I want to talk about error tracking within our project. This is an especially important scenario to think of within an application like ours. This is a mono-repo application, which by default means it has a lot of moving parts. And that means a lot of things that can go wrong and while you as a developer can capture many errors on your own while you're developing your users will most likely use your app in a completely different way And you need to be able to track the errors of your users not just your developer errors. So what I'm going to do here is create an error scenario and then I'm going to show you the current way we can track errors thanks to convex error tracking and then we're going to enhance that by adding production grade error tracking with Sentry.
So let's go ahead and create an error scenario first. So what I would like you to do if you haven't is just run turbo dev and I want you to go to localhost 3000 where your current authenticated application is. And just to make this easier go inside of apps web app dashboard page You can go ahead and remove this div with JSON stringify because it just seems to be taking space at the moment. Great. We now have just the add button.
So now if you go ahead inside of your API users add and after successful identity and after successful organization go ahead and throw a new error here called tracking test. So what happens now? First, make sure that inside of your workspace backend, the functions are successfully compiled. After that, go ahead and click add. What you're going to see are two issues appearing right here, error tracking test.
And while this is perfectly fine when you are the developer and you encounter this issue, what if this happened to one of your users and you had absolutely no idea it happened to them? Well, thanks to Convex, there is one thing we can already track. So if you go inside of your convex dashboard and go inside of your project here you can see the high failure rate and you can also individually click on functions and click on add and in here you can find all the logs that went wrong. But the problem with this is it doesn't really tell you much about the user who triggered this error. So it is tracking the back-end error but it cannot really tell you what went wrong, how did this happen, it cannot give you the breadcrumbs that led to this event.
Because of this we're going to integrate Sentry, production grade error tracking. So you can use the link on the screen or the link in the description to let them know you came from this video. And now go ahead and simply create an account. After you've created your account, since it's a completely new account for me, I have no projects here so this is how it looks like. And in order to add Sentry to your project, you can access the documentation very easily by clicking on Help and then clicking in the documentation.
And in here you immediately have Next.js integration. And in here, let's go ahead and let's run sentry-vizier-latest-i nextjs and the way we're going to run this is like the following I want you to go inside of apps and then I want you to go inside of web specifically. So make sure that you are inside of a web. You should be able to see the app folder, lib, middleware, all of those things. And now instead of running NPX, we will run PNPM DLX Sentry Wizard at latest, and we are going to pre-select next.js option here and now let's go ahead and select the following.
So it's warning us that we have some untracked files in our repository. The reason it's warning us about this is because it might overwrite some files but we changed this just to demonstrate the error so this is perfectly fine. So do you want to continue anyway you can press yes and now it's asking us if we are self-hosting Sentry or if we are using the sas version so we are using the sass version so make sure to select that. Do you already have a sentry account? Yes, we just created one.
So now let's go ahead and create a new project which I'm going to call echo tutorial like that and go ahead and click continue and now you can return into your terminal. So in here you have to select your package manager using the arrow keys so I'm going to select pnpm and press enter and now sentry nextjs is being installed with pnpm. Now it's asking us some additional configuration questions. So this will usually depend on your complex application and what you want but for this tutorial you can select yes for this. This will basically allow Sentry to work even with ad blockers.
So yes for the enable tracing, yes. And the session replay, a very cool feature. Select yes for that as well. Logs, yes. And let's also select yes for the example page so we can test the Sentry setup properly.
And in here we have one warning. Sentry SDK is only compatible with TurboPack on Next.js version 15.3.0 but we are using an older Next.js version. So the way to fix this is to remove ____ Turbo or to upgrade the Next.js version. We're going to use the first option simply because this is the version that Shatien Monorepo template suggested at the time of making this tutorial. So just to keep things simpler, we're just going to remove dash dash turbo.
Now just to remind you, TurboPack and TurboRepo are not the same things. This means it's not compatible with the bundler it doesn't mean it's not compatible with the mono repo those are two separate things just to make that clear and here's a little note that the sdk will continue to work for non-turbo pack production build so don't have to worry. And let's go ahead and press I understand and also one important thing it failed to add this to gitignore because we have a global gitignore so don't worry we're going to think of this as well. And now let's go ahead and select yes for the CI CD tool here and then you will get your century out token. Go ahead and copy it and then you can go inside of your web application here.
So web and find dot environment dot local and after a clerk I will add sentry and I'm just gonna add it here and now let's press yes, continue there we go so now we have to do a couple of things here. The first thing I'm going to do is I'm going to add this to my git ignore because it warned me that it wasn't able to do that. So I'm going to go inside of this git ignore here and after local environment files I will add sentry environment files and paste it here. And now if you go inside of your apps web and you will see that this is grayed out because it is now in gitignore. And you can also see a bunch of new files being written here.
All of that was added by Sentry. Now what we have to do is we have to temporarily remove Turbo from our dev command. So that is also quite easy to do. So inside of our app where we just added Sentry, let's go inside of package.json here and let's simply remove the dash dash turbo back. That's all we have to do.
Make sure you've done that inside of the web app. And now I believe that one thing I really want to do is just going to root of my application and just run PMPM install just like this and Now let's go ahead and let's do PMPM. My apologies. Let's do turbo dev And let's focus on the web to make sure that it is working. Let's make sure nothing is failing here.
You can see we don't have any warnings because we removed the TurboPack flag. And now let's go back to localhost 3000 here. Let's see if it will load fine. Looks like it's loading just fine. And now let's just visit the SentryError page that was created.
So apps web app century example page. So localhost 3000 century dash example dash page. There we go. So it looks like my events are blocked here. So I'm just going to go ahead and disable my uBlock origin here.
There we go. So that fixed the error. Make sure you don't have any extensions, at least for this development mode. So let me just quickly show you the url that I'm on here this is the url that I'm on just so you are aware and go ahead and click throw sample error and you will get the message error sent to sentry And now if you go inside of your project here, maybe do a refresh here, you should be able to now see your errors. There we go.
So 13 and 12 seconds ago, we triggered both API error and the front-end error. And this is now a completely different experience of error tracking. So it is absolutely amazing that Convex has built in error tracking, but Sentry is built for this kind of things. You can see that it will exactly tell you what browser version this happened on, the operating system, even the commit if you want to connect your repository to it. It will tell you the exact route this happened on.
It will tell you every single thing. If you scroll a little bit down it will tell you that it happened in app sentry example page page.tsx in onclick at this exact line. If you want to you can also see a session replay to kind of guess what happens. So this is insanely impressive to me because they are not recording your screen, they are recreating what could have possibly happened. So that's what I think it's absolutely amazing.
You can see that a button was clicked and then something appeared at the bottom. That is exactly what happened if you remember. This button and then this appeared. I think this is absolutely insane. So you can see what I mean when I say production level error tracking.
And in here, you can see the breadcrumbs. So you can see exactly what happened starting from when the person clicked on something. As you can see, we clicked on something, we clicked on the button, and then we did this API request and that threw back an error so that's how you can track exactly what happened not only that but you can also see all the information about the user that this happened to. So by scrolling even further, you can see even more examples of how this happened. So basically, just by this super simple button click, you get all of this amazing information to understand where the error comes from.
Because that's what you need to know if your users are creating errors. There is no other way for you to know. You can also see the exact React version. So you can basically do absolutely everything to become this user, because it's super hard when you cannot reproduce something, but your users keep getting errors. This is how you fix those issues.
And this was barely scratching the surface of Sentry. So what I just did is showing you the most basic error tracking it offers. They offer so many things. This can actually turn into its own little Jira or Trello board where you can resolve issues, where you can get notifications. If it happens again, I'm gonna put a little screenshot.
When I develop my applications, I get Gmail notifications from Sentry whenever something goes wrong. And this basically tells me if I'm, I don't know, in a supermarket, it tells me, hey, your users are having serious errors. You should go check this out. And that saved me many times because I did not encounter those errors, but for some reason my users did. And by tracking the logs, that's how I fixed the issue.
By looking at the session replay, I understood, okay, I know exactly where this is, now I can reproduce it. So that is the power of Sentry. But now what we're going to do even further is we're going to try to make Sentry log our convex error because right now our users.ts here is throwing an error but by default I'm pretty sure Sentry will not catch that because convex is an entirely different environment. So what we're going to do is we're going to connect convex and Sentry together. So now let's go ahead and let's test this convex error one more time.
So I'm going to go to localhost 3000 again here and I'm going to click add. So again we get this convex error and let's see if that will be tracked in here automatically. So let me just go inside of my issues And you can see that we do have this error here. So Sentry does an amazing job of figuring this out as well, but it only knows this because it was called by the client. So it actually has limited knowledge of why this happened but there is a way to connect convex error tracking with Sentry to give it full back-end and front-end knowledge about this.
So in order to do that you have to go back inside of your convex dashboard here click into settings and then click into integrations and the first option here is sentry so let's go ahead and click a plus button here and now we have to pass the sentry data source name So what I'm going to do now is find that by closing my packages and by going inside of my apps web and I think that you can just find a sentry edge config or server config. I think they use the exact same DSN right here. There is probably some other way you can obtain the DSN, but this works as well. So just go ahead and add it here. You don't have to pass anything in here and click save and you can see that it is active.
So let's go ahead and try this again. I'm going to go ahead now inside of here again and I'm going to throw this error again. And I believe that now if I go back inside of my issues here, Maybe it just repeated this error. Let's try throwing it a few more times. I'm trying to make it appear again.
Maybe we'll have to develop another error to see it here. And let's just confirm that all of this is working correctly here. Let's refresh a few more times. There we go. And now you can see the difference.
So look at the first example. In the first one, it didn't exactly know why it happened, but in here it knows exactly that it was user's ad. At least I think that's the order. I might have confused it, but basically one of these is now connected. Maybe it's actually this one.
I'm not sure because in here you can see the exact file where it happens. So maybe I told you incorrectly, I was fooled by the name here. Let's simply check out the both of them and then see what is the one with more information. I have a feeling it is this one right here because it tells me the exact name of the file where this happens. So basically it was that easy for us to connect the convex and now we have backend information as well.
So the function name was users add And you can also see the exact user that this happened to, thanks to our clerk integration. So your users are now no longer anonymous. You can now also definitely know to whom this happened. Absolutely amazing. And you can see the SDK is convex and diversion.
So this is how you track errors in production grade environments. This is how it works. And again, this is just scratching the surface. There are so many different things that you can look at here. Sentry isn't just for errors.
You can also track dead clicks, slow SSR. So whatever is going wrong with your app, you can track here. All the routes, all that's good, all that's bad, all of those things are available to track here. So I as I said I barely scratched the surface of this. I highly advise you to go ahead and explore this yourself.
So now that we have this implemented, I do want to try and confirm a very important thing and that is do our apps still work? So the one thing that I want you to do, I want you to go inside the terminal, focus on the web dev And I want you to scroll a little bit through here. And I want you to pay good attention if you see something called open telemetry. The reason I'm telling you to pry your eyes in trying to find that is because there actually is a little troubleshooting guide here, which might or might not happen. It did happen to me the first time I developed this, so I know it's possible to happen and it is this.
Import in the middle external package errors. So, pry your eyes into this. Import in the middle and try and find something in here or maybe just search import in the middle. So, you can see that Right now it is not happening for me anywhere. But this is how I'm going to 100% confirm.
I'm going to run TurboBuild. So build is the ultimate, okay, it works and I can deploy it. So looks like this is working on the widget. It's still building on web. So let's go ahead and wait till the web finishes to determine whether we need to change anything or not.
And here we go. So three successful builds means that everything is okay. And I still can't find any open telemetry or import in the middle issues in my builds here. But I am going to try and find a screenshot of that happening and post it here so that you can recognize it if that's something that you are getting. And if you are getting it, they have a guide on how to resolve it.
So you have to go instead of their documentation, Next.js, click on troubleshooting here and find PNPM resolving import in the middle external package errors. So when using PNPM, you might encounter errors related to packages that can't be external, particularly packages like import in the middle and require in the middle. So it is because PNPMs strict dependency management and hoisting behavior. Now, there are a couple of ways you can fix it. One way that I fixed it immediately in my previous project was by adding these two inside of my npmrc file.
So this is what you would do. You would go inside of npmrc and you would paste those two here. And after that, what I did was I simply run pnpm install in the root of my application. And you will be asked if you want to restart node modules from scratch. So in here I selected true.
So let's see what happens now. I'm purposely doing this just in case some of you are having this issue because I was able to get that problem. So let's go ahead and try again. Does TurboDev work now? Math is obviously working.
Dev is working. Web is working. Backend is working. Perfect. Let's try TurboBuild just to confirm 3 successful.
Looks like everything works just fine. Amazing, amazing job. So obviously I'm gonna keep an eye on this if it happens and keep you alerted in case you are having some errors. Always make sure to watch a little bit more of my tutorial because sometimes I fix errors from previous chapters in the next chapter, right? So don't worry, I will keep an eye on everything here and test it as much as I can to make sure you and I are seeing the same thing in our consoles here.
Amazing, amazing job. So we just developed error tracking by connecting convex to centric. Now let's go ahead and commit these changes here. So I'm going to go ahead and add all of these changes. I'm going to call this 05 I believe error tracking like so.
I'm going to click commit. I'm going to click on main down here create a new branch 05 error tracking like that and I'm going to publish this branch and then I'm going to go ahead inside of my echo tutorial repository here and I'm going to open a new pull request. Let's go ahead and review in case we have some serious issues, but I think it's mostly going to be okay. And here we have the summary by CodeRabbit. So we introduced the Sentry error monitoring and performance tracking across the application, including both server and client environments.
And of course, we added this dedicated page for testing Sentry and we added a back-end API endpoint. We didn't do this manually the Sentry Wizard did this for us just in case you're confused. We removed the display of the user list because it was it was interfering with our work at the moment. In here as always we have a file by file change, but we don't really have to review most of this because a Sentry Wizard added it like this. So I don't really know if we should move this or not.
So yes, it is adding comments for this Sentry example API, which we're going to remove in the next chapter. So really no need to fix something that was just used as an example here, but obviously all correct comments from CodeRabbit here. And in here it's suggesting changing the traces sample rate. Not so sure about that. I'm gonna have to explore about it to see if this is a true statement or not but again the Sentry Wizard set it up like this so I'm going to leave it like this.
Let's go ahead and merge this pull request and after you have merged it let's go ahead and go inside of error tracking here let's click back on main and let's click this button right here to synchronize our changes just like that there we go and then click on graph here and confirm that you have detached in 05 error tracking and then merged it back here. Amazing, amazing job! I believe that marks the end of this chapter as well. Amazing job and see you in the next chapter.