<commit_before># Costanza

Frontend error tracking toolkit: Own your own domain

Provides a [Node.js domains][node_domains] inspired async error-tracking system for frontend clients. This allows for tracking errors with more than the `Undefined is not an object` level of detail that many implementations of generic `window.onerror` provide.

```
onerror:
  msg: Uncaught TypeError: 'undefined' is not an object
  url: http://localhost/home.js
  line: 1
```

But with Costanza the logged error is much more expressive:

```
Costanza error:
  type: javascript
  section: thorax-exception: home ;; DOM-event:click .js-big-red-button

TypeError: 'undefined' is not an object
    at bigRedButtonHandler (http://localhost/home.js:1:129)
    at http://localhost/base.js:1:2221
    at ret (http://localhost/base.js:1:9860)
```

Showing that the error occurred in the `click .js-big-red-button` event handler of the throax `home` view as well as providing wthe stack trace associated with that event.

## Features

- Automatically associating callbacks and events with the code group that created them
- Tracking global javascript errors
- Tracking resource load failures

## Usage

Initialize the library using the `Costanza.init` method, passing a callback that will handle errors. This callback should send the error info to your centralized tracking server.

```javascript
Costanza.init(function(info, rawError) {
  $.ajax({
    url: myAnalyticsServer,
    method: 'POST',
    data: info
  });
});
```

This is the minimum required to use the library, but the fidelity of the error tracking is greatly improved if code is associated with known sections. Sections allow for a unique name to be associated with a code execution path. Should an error occur within the section or one of it's anonymous sections, this unique name will be included in the error result, easing debugging.

The easiest way to create a section is with the `run` method, which will immediately execute.

```javascript
Costanza.run('unique-name', function() {
  // Do stuff that fails
});
```

Callbacks may also be created with sections for later execution:

```javascript
var callback = Costanza.bind('another-unique-name', function() {
  // Bang!
});
```

Anonomyous sections may be created within other known sections. When these child sections execute, they will do so using the same identifier pased to the parent section. This is done automatically for callbacks passed to `setTimeout`, `setInterval`, and `addEventListener` by default.

```javascript
Costanza.run('yet-another-unique-name', function() {
  setTimeout(function() {
    // A later bang!
  }, 1000);
});
```

Ideally new named sections are created for any logical entry point into the system from the event loop. Things like DOM event handlers and ajax callbacks are prime candidates for creating named sections. Plugins such as costanza-thorax allow for doing this in an automated fashion. (Don't see a plugin for your framework of choice? [Send over a PR][pull_request]!

### Implementation Warning

This code hijacks majors portions of built-in prototype objects. This should fail-safe but is not guaranteed to do so. Use only after considering the risks. User's who would like to avoid prototype extension may pass the `safeMode` option to avoid altering host objects. `safeMode` users will need to manually wrap callback functions to ensure that stack traces are available for methods that are executed on subsequent event loops.


```javascript
Costanza.init(function(info, rawError) {
  $.ajax();
}, {safeMode: true});

Costanza.run('still-yet-another-unique-name', function() {
  setTimeout(Costanza.bind('still-yet-another-unique-name', function() {
    // A later bang!
  }), 1000);
});
```

## API<commit_msg>fix a few minor typos<commit_after># Costanza

Frontend error tracking toolkit: Own your own domain

Provides a [Node.js domains][node_domains] inspired async error-tracking system for frontend clients. This allows for tracking errors with more than the `Undefined is not an object` level of detail that many implementations of generic `window.onerror` provide.

```
onerror:
  msg: Uncaught TypeError: 'undefined' is not an object
  url: http://localhost/home.js
  line: 1
```

But with Costanza the logged error is much more expressive:

```
Costanza error:
  type: javascript
  section: thorax-exception: home ;; DOM-event:click .js-big-red-button

TypeError: 'undefined' is not an object
    at bigRedButtonHandler (http://localhost/home.js:1:129)
    at http://localhost/base.js:1:2221
    at ret (http://localhost/base.js:1:9860)
```

Showing that the error occurred in the `click .js-big-red-button` event handler of the throax `home` view as well as providing the stack trace associated with that event.

## Features

- Automatically associating callbacks and events with the code group that created them
- Tracking global javascript errors
- Tracking resource load failures

## Usage

Initialize the library using the `Costanza.init` method, passing a callback that will handle errors. This callback should send the error info to your centralized tracking server.

```javascript
Costanza.init(function(info, rawError) {
  $.ajax({
    url: myAnalyticsServer,
    method: 'POST',
    data: info
  });
});
```

This is the minimum required to use the library, but the fidelity of the error tracking is greatly improved if code is associated with known sections. Sections allow for a unique name to be associated with a code execution path. Should an error occur within the section or one of its anonymous sections, this unique name will be included in the error result, easing debugging.

The easiest way to create a section is with the `run` method, which will immediately execute.

```javascript
Costanza.run('unique-name', function() {
  // Do stuff that fails
});
```

Callbacks may also be created with sections for later execution:

```javascript
var callback = Costanza.bind('another-unique-name', function() {
  // Bang!
});
```

Anonomyous sections may be created within other known sections. When these child sections execute, they will do so using the same identifier pased to the parent section. This is done automatically for callbacks passed to `setTimeout`, `setInterval`, and `addEventListener` by default.

```javascript
Costanza.run('yet-another-unique-name', function() {
  setTimeout(function() {
    // A later bang!
  }, 1000);
});
```

Ideally new named sections are created for any logical entry point into the system from the event loop. Things like DOM event handlers and ajax callbacks are prime candidates for creating named sections. Plugins such as costanza-thorax allow for doing this in an automated fashion. (Don't see a plugin for your framework of choice? [Send over a PR][pull_request]!)

### Implementation Warning

This code hijacks majors portions of built-in prototype objects. This should be fail-safe but is not guaranteed to do so. Use only after considering the risks. Users who would like to avoid prototype extension may pass the `safeMode` option to avoid altering host objects. `safeMode` users will need to manually wrap callback functions to ensure that stack traces are available for methods that are executed on subsequent event loops.


```javascript
Costanza.init(function(info, rawError) {
  $.ajax();
}, {safeMode: true});

Costanza.run('still-yet-another-unique-name', function() {
  setTimeout(Costanza.bind('still-yet-another-unique-name', function() {
    // A later bang!
  }), 1000);
});
```

## API
{'fraction_non_alphanumeric': 0.08542580045170718, 'fraction_numerical': 0.006111332536203003, 'mean_word_length': 4.486880466472303, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '846434', 'n_tokens_mistral': 2042, 'n_tokens_neox': 1913, 'n_words': 948}