Skip to content

improve the setup description #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 31 commits into from
Jun 7, 2019
Merged

improve the setup description #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
b666d7d
correct filters config setup description
vanesa May 30, 2019
0ff4836
add missing comma
vanesa May 30, 2019
6c01b61
update readme
vanesa May 30, 2019
3b81967
improve setup guide
vanesa May 31, 2019
ac43345
Update dependency @types/lodash to v4.14.133
renovate-bot Jun 1, 2019
a98294e
Update dependency prettier to v1.17.1
renovate-bot Jun 1, 2019
7833115
Update dependency @types/mocha to v5.2.7
renovate-bot Jun 1, 2019
253d33d
Update dependency @types/sinon to v7.0.12
renovate-bot Jun 1, 2019
a5d589a
Update dependency tslint to ^5.17.0
renovate-bot Jun 1, 2019
2312e7a
fix prettier
vanesa Jun 3, 2019
4e6d040
add non-capturing regex group example
vanesa Jun 3, 2019
724bffc
remove commas
vanesa Jun 3, 2019
efa31fa
remove more commas
vanesa Jun 3, 2019
bba3ca9
when only given one project and no filters, always match to that project
vanesa Jun 3, 2019
21f9b07
cleanup code (#44)
vanesa Jun 5, 2019
42b609d
README tweaks
christinaforney Jun 5, 2019
d1dc7be
correct filters config setup description
vanesa May 30, 2019
af9342c
update readme
vanesa May 30, 2019
984c008
improve setup guide
vanesa May 31, 2019
b55b84d
fix prettier
vanesa Jun 3, 2019
8753365
add non-capturing regex group example
vanesa Jun 3, 2019
085b861
remove commas
vanesa Jun 3, 2019
92e2f2e
remove more commas
vanesa Jun 3, 2019
0a0b95c
when only given one project and no filters, always match to that project
vanesa Jun 3, 2019
f15a648
README tweaks
christinaforney Jun 5, 2019
3a9f0f6
only require projectId to render Sentry link, better breadcrumb for m…
vanesa Jun 5, 2019
07bc987
safeguard user error of empty repositories array
vanesa Jun 5, 2019
d98eb24
merge conflicting files
vanesa Jun 5, 2019
0a943d9
fix prettier
vanesa Jun 5, 2019
8789806
address code review comments, update tests
vanesa Jun 7, 2019
5fb0e16
Update README.md
vanesa Jun 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 159 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
[![build](https://travis-ci.org/sourcegraph/sourcegraph-sentry.svg?branch=master)](https://travis-ci.org/sourcegraph/sentry)
[![codecov](https://codecov.io/gh/sourcegraph/sourcegraph-sentry/branch/master/graph/badge.svg)](https://codecov.io/gh/sourcegraph/sourcegraph-sentry)

Sentry helps devs track, organize and break down errors more efficiently, facilitating their debug process. We want to make it more convenient for developers to access Sentry's error tracking tools directly from the code that is doing the error handling, code such as `throw new Error(QUERY)`, `console.log(QUERY)`, `console.error(QUERY)` etc..
Sentry facilitates the debugging process by helping developers track, organize, and break down errors more efficiently. At Sourcegraph, we want to make it more convenient for developers to access Sentry's error tracking tools directly from the code that is doing the error handling. For example: `throw new Error(QUERY)`, `console.log(QUERY)`, and `console.error(QUERY)`.

The Sentry extension renders a `View logs in Sentry` next to error throwing statements, linking directly to the corresponding Sentry issues stream page. Links are rendered when viewing files on [Sourcegraph](https://sourcegraph.com), GitHub and GitLab.
The Sentry extension renders `View logs in Sentry` next to error throwing statements, and links directly to the corresponding Sentry issues stream page. Links are rendered when viewing files on [Sourcegraph](https://sourcegraph.com), GitHub, and GitLab.

- **Sentry: Show/hide Sentry**: toggles Sentry links decorations with each matching error handling code.

Expand All @@ -17,113 +17,201 @@ The Sentry extension renders a `View logs in Sentry` next to error throwing stat

## Language support

To work, the Sentry Sourcegraph extension must know how to recognize instances of error handling and/or exception throwing for each language. The first version will support:
The Sentry Sourcegraph extension uses common error handling and/or exception throwing patterns specific to each language to identfy Sentry relevant lines of code. The following languages are currently supported:

- TypeScript
- Go
- JavaScript
- Python
- Java
- TypeScript, JavaScript ( e.g. `throw new Error()`, `console.error()`)
- Go ( e.g. `err.message()`)
Copy link
Contributor

@felixfbecker felixfbecker Jun 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've never seen this code in Go. Do you mean something like error.New()?

- JavaScript ( e.g. `console.error()`)
- Python ( e.g. `raise TypeError()`)
- Java ( e.g. `logger.error()`)

See the [default error patterns](https://sourcegraph.com/github.com/sourcegraph/sourcegraph-sentry@master/-/blob/src/extension.ts?diff=21f9b0716040dd96f917580ec4cacd59f3f1b5be&utm_source=chrome-extension#L11-25).

## Setup
If you need to match more specific patterns in your codebase, you can configure them through [line matches](#improving-error-pattern-recognition-for-your-organization).

Set the following configurations in your settings:
## Basic Setup

In your Sourcegraph settings (user, organization, or global), add the following configuration:

```
"sentry.organization": "[Sentry organization name]",
"sentry.decorations.inline": true,
"sentry.organization": "<your_sentry_organization>",
"sentry.projects": [
{
"name": "[Project name for the config overview, e.g. Webapp errors]",
"projectId": "[Sentry project ID, e.g. "1334031"]",
"linePatterns": [
// List of RegExp patterns that match error handling code, e.g. "throw new Error+\\(['\"]([^'\"]+)['\"]\\)",
// !! Make sure to capture the error message in a RegExp group !!
]
"filters": {
[
"repositories": [
// List of RegExp repo names asociated with this Sentry project
],
"files": [
// List of RegExp that matches file format, e.g. "\\.tsx?",
// or for more specific matching, folder matching, e.g. "(?:web|shared|src)\/.*\\.tsx?"
],
{
// All matching error statements in your sourcegraph instance will link to this project
"projectId": "<your_sentry_project_id>",
}
}
]
```

For organizations, we recommend to set this once by the site admin in the org or global settings, so that individual org users do not have to configure this individually.

With this simple configuration, any error that matches the default patterns will link to the specified Sentry organization and project.

To find your Sentry organization and project ID, go to [sentry.io](http://sentry.io) and look at the URL when on your project page, e.g.:

```
https://sentry.io/organizations/sourcegraph/events/?project=1251215
```

In the above, `sourcegraph` is the organization and `1251215` is the project ID.

## Important features:
## Mapping multiple Sentry projects to various repositories

File patterns can also be narrowed down to certain folders by specifying this in the RegExp:
Some organizations have multiple Sentry projects that capture errors from various repositories within their organization. Inside each Sentry project, use repository `filters` like so:

```
Copy link
Contributor

@felixfbecker felixfbecker Jun 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make this json for syntax highlighting (other codeblocks too)

...
"files": ["(?:web|shared|src)\/.*\\.tsx?"]
...
"sentry.decorations.inline": true,
"sentry.organization": "<your_sentry_organization>",
"sentry.projects": [
{
// All repositoryA error patterns link to Project A in Sentry
"projectId": "<project_a>",
"filters": [
{
"repositories": [
"myorg/repositoryA$" // Regexp matching repositories that report to this Sentry project
]
}
]
},
{
// All repositoryB error patterns link to Project B in Sentry
"projectId": "<project_b>",
"filters": [
{
"repositories": [
"myorg/repositoryB$"
]
}
]
}
]
```

## Examples
In this example, errors found in `repositoryA` will link to `project_a`, and errors in `repositoryB` will link to `project_b` in Sentry.

- TypeScript
## Mapping a single repository to multiple Sentry projects

Configuration:
Some organizations will have different parts of their code base map to different Sentry projects. For example, all frontend code is sent to one Sentry project, and all backend code is sent to another.

```
"sentry.decorations.inline": true,
"sentry.organization": "sourcegraph",
"sentry.projects": [
You can add multiple Sentry projects and add file `filters` to match specific files or folders, like so:

```
"sentry.decorations.inline": true,
"sentry.organization": "<your_sentry_organization>",
"sentry.projects": [
{
"name": "sourcegraph",
"projectId": "1334031",
"linePatterns": [
"throw new Error+\\(['\"]([^'\"]+)['\"]\\)",
"console\\.(warn|debug|info|error)\\(['\"`]([^'\"`]+)['\"`]\\)"
]
// All JS files link to Project A in Sentry
"projectId": "<project_a>",
"filters": [
{
"repositories": "sourcegraph\/sourcegraph",
"files": ["web\/.*\\.ts?"],
},
"files": [
"\\.js?" // RegExp that matches JavaScript files
]
}
]
},
{
// All Go files link to Project B in Sentry
"projectId": "<project_b>",
"filters": [
{
"files": ["sourcegraph-subfolder\/.*\\.tsx?"]
"files": [
"\\.go?"
]
}
]
}
]
```

Now, errors found in JS files will link to `project_a` and errors in Go files will link to `project_b` in Sentry.

You can also match repository subdirectories using a regex (e.g. `"(?:web|node)\/.*\\.tsx?"` to match any files with the `.tsx` extension within directories named `web` or `node`).

## Improving error pattern recognition for your organization

By default, the extension matches error messages from a few popular languages. However, you may need to define your own patterns to enhance matches for your specific codebase, or that we do not currently support.

To do this, add a regex to your Sentry project config that captures the static error message generated. For example, to match JS/TS throw statements:

```
"sentry.projects": [
{
// Frontend errors
"projectId": "<project_a>",
"linePatterns": [
// Matches JS/TS throw statements:
"throw new [A-Za-z0-9]+\\(['\"]([^'\"]+)['\"]\\)"
]
}
]
]
```

The error message should always be captured by the capture group \$INDEX=0. All other capture groups should be made optional with `?:`. For instance, in the above example, note how the first regex group is ignored with `?:`. It will match a variety of `throw new` error types, but doesn't need to be captured. The second regex group captures the error string, which will be used as the search when linked to Sentry.

## Language Specific Examples

- TypeScript

Configuration:

```
"sentry.decorations.inline": true,
"sentry.organization": "sourcegraph",
"sentry.projects": [
{
// Web errors
"projectId": "1334031",
"filters": [
{
"repositories": "sourcegraph/sourcegraph",
"files": ["web/.*\\.ts?"]
},
{
"files": ["sourcegraph-about/.*\\.tsx?"]
}

],
"linePatterns": [
"throw new [A-Za-z0-9]+\\(['\"]([^'\"]+)['\"]\\)",
"console\\.(?:warn|debug|info|error)\\(['\"`]([^'\"`]+)['\"`]\\)"
]
}
]
```

- [On Sourcegraph](https://sourcegraph.com/github.com/sourcegraph/sourcegraph/-/blob/browser/src/libs/github/file_info.ts#L22)
- [On GitHub](https://github.com/sourcegraph/sourcegraph/blob/master/browser/src/libs/github/file_info.ts#L22)

- Go

Configuration:
Configuration:

```
"sentry.decorations.inline": true,
"sentry.organization": "sourcegraph",
"sentry.projects": [
"name": "Dev env errors",
"projectId": "213332",
"linePatterns": ["errors\\.New\\(['\"`](.*)['\"`]\\)"],
"filters": [
{
"repositories": ["sourcegraph\/sourcegraph", "sourcegraph\/dev-repo"],
"files": ["/auth\/.*.go?/"],
},
```
"sentry.decorations.inline": true,
"sentry.organization": "sourcegraph",
"sentry.projects": [
{
"repositories": ["/dev-env/"]
// Dev environment errors
"projectId": "213332",
"filters": [
{
"repositories": ["sourcegraph/sourcegraph", "sourcegraph/dev-repo"],
"files": ["auth/.*.go?/"]
},
{
"repositories": ["/dev-env"]
}
],
"linePatterns": ["errors\\.New\\(['\"`](.*)['\"`]\\)"]
}
],
]

```
]
```

- [On Sourcegraph](https://sourcegraph.com/github.com/sourcegraph/sourcegraph/-/blob/cmd/frontend/auth/user_test.go#L54:19)
- [On GitHub](https://github.com/sourcegraph/sourcegraph/blob/master/cmd/frontend/auth/user_test.go#L54)
- [On Sourcegraph](https://sourcegraph.com/github.com/sourcegraph/sourcegraph/-/blob/cmd/frontend/auth/user_test.go#L54:19)
- [On GitHub](https://github.com/sourcegraph/sourcegraph/blob/master/cmd/frontend/auth/user_test.go#L54)

- JavaScript

Expand Down
Loading