Skip to content

About

Prototype hackweek Sentry SDK for Dogescript — not an official Sentry SDK

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

sentry-dogescript

Important

Prototype hackathon code. Built in a few hours for a Sentry hackweek. This is not an official Sentry SDK, is not affiliated with or supported by Sentry, and is nowhere near production-ready. Do not point it at anything you care about.

Stylized Dogescript logo in Sentry style

wow. such error monitoring. very Sentry SDK. much Dogescript.

init, captureMessage, captureException — written in Dogescript, compiled to JavaScript, sending real Sentry envelopes over a real socket.

so sentry-dogescript as sentry

plz sentry.init with 'https://<public_key>@o0.ingest.sentry.io/42'

plz sentry.captureMessage with 'HAI WORLD. such observability'

Install

Not published to the public registry. Install it from a path or a packed tarball:

npm install /path/to/sentry-dogescript
npm pack                                    # in this repo -> sentry-dogescript-0.1.0.tgz
npm install ../sentry-dogescript-0.1.0.tgz  # in your project

What you get, and whether you need the compiler

The package ships both the compiled JavaScript and the Dogescript source:

in the tarball what it is
dist/sentry.js compiled CommonJS. This is main — it is what require loads
src/sentry.djs the Dogescript source, so you can read it and rebuild it
README.md this

You do not need the Dogescript compiler to use this SDK. require('sentry-dogescript') resolves to dist/sentry.js, which is plain JavaScript with no dependencies beyond Node's built-in http, https and crypto. Install it into a plain JavaScript project and it just works:

const sentry = require('sentry-dogescript');
sentry.init('https://<public_key>@o0.ingest.sentry.io/42');
sentry.captureMessage('hello from ordinary javascript');

You need the compiler only to build your own .djs files — which is the entire point of installing this, so realistically you want it:

npm install --save-dev dogescript@2.4.3

Take that from the npm registry, not from GitHub. npm i github:dogescript/dogescript appears to work and then does not: the package's files field is dist/*, dist/ is a build artifact that is not committed, and you end up with a dogescript package containing a README and nothing to run. The registry tarball has the built compiler.

Quick start

app.djs:

so sentry-dogescript as sentry

plz sentry.init with 'http://testkey@127.0.0.1:3004/42'

such dispenseTreat much shibe
    very note is 'much treat dispensed for '
    note is note + shibe
    very id is plz sentry.captureMessage with note
wow id

very sent is plz dispenseTreat with 'Kabosu'
very line is 'captureMessage -> '
line is line + sent
plz console.loge with line

Dogescript compiles to stdout, so building is a redirect:

dogescript app.djs --beautify > app.js
node app.js

API

init

plz sentry.init with '<scheme>://<public_key>@<host>:<port>/<project_id>'
plz sentry.init with dsn {'debug': true}

Parses and stores the DSN for later calls; returns the parsed object. The port is optional — https defaults to 443, http to 80.

options.debug (default false) turns on a one-line note to stderr for every successful send. Off, the SDK says nothing on success. See Logging below.

Call it once at startup.

captureMessage

very id is plz sentry.captureMessage with 'some text'
very id is plz sentry.captureMessage with 'some text' someCallback

Sends a level: info event with a logentry. Returns the 32-hex event id.

captureException

very id is plz sentry.captureException with err
very id is plz sentry.captureException with err someCallback

Takes a real Error. Reads err.name into exception.values[0].type, err.message into value, and parses err.stack into exception.values[0].stacktrace.frames. Returns the event id.

The callback

Both capture functions return the event id immediately and send in the background — nothing to await, nothing to flush. The optional last argument is an error-first callback, and it is the seam for anything you want to know about the send:

such barkTheReply much oops status body
    rly oops
        very sad is 'much fail. very sad. '
        sad is sad + oops.message
        plz console.loge with sad
        amaze
    wow
    very yay is 'wow. sentry sez '
    yay is yay + status
    yay is yay + ' '
    yay is yay + body
    plz console.loge with yay
wow

plz sentry.captureMessage with 'HAI WORLD' barkTheReply
  • success — done(null, statusCode, body), where body is Sentry's {"id":"<event_id>"}
  • transport failure — done(err)
  • init never called — done(err) and nothing is sent

Logging

The SDK writes nothing to stdout, ever. Your application's stdout is yours; an error reporter that prints on every captured event would spam a real service's logs. Use the callback if you want per-send visibility.

It writes to stderr in exactly three cases:

when message why it is not silent
init was never called such unconfigured. plz init first. very sad misuse — silently dropping every event is worse
the request failed very network. much broken. sentry send failed: ... your telemetry is going nowhere and you want to know
only with debug: true wow. sentry sez 200 {"id":"..."} you asked for it

The first two also invoke your callback if you supplied one, so you can handle them yourself; they still go to stderr because swallowing a misconfigured or broken transport is the worse default.

wow. sentry sez is too good to delete, so it lives behind debug — opt in with plz sentry.init with dsn {'debug': true}.

Wiring it to your errors

Dogescript has no try, no catch and no throw (see the limitation below), so you hand captureException an error you got some other way. A process-level lookout is the idiomatic move:

process dose on with 'uncaughtException' much boom
    very oops is plz sentry.captureException with boom
    very yell is 'captureException -> '
    yell is yell + oops
    plz console.loge with yell
wow&

Registering that listener also stops Node from exiting on the throw, so the in-flight send completes. process dose on with 'unhandledRejection' works the same way for promises.


Working on this repo

src/sentry.djs        the SDK
examples/example.djs  a consumer, installing the SDK the documented way
mock-ingest.js        a local stand-in for Sentry ingest, so this repo tests itself
dist/sentry.js        compiler output — npm run build regenerates it, do not edit
npm install       # the compiler
npm run build     # src/sentry.djs -> dist/sentry.js
npm run mock      # mock ingest on 127.0.0.1:3004
npm run example   # build, then run examples/ against the mock

examples/ is a separate package that depends on sentry-dogescript as file:.., so it goes through the same so sentry-dogescript as sentry resolution a stranger would. It is not compiled together with src/.

npm run mock validates the auth header, envelope structure, event id format, timestamp and frame ordering, prints what it received, and rejects anything malformed with a 400 and a reason — so bugs surface there rather than as a silent 200. Set PORT to move it off 3004.

Expected output from npm run example:

much message. very id 926ec3b22e28d306a90e63ed8935dedd
much exception. very id b128e31695adfef5b74aeab11dc83a54
wow. sentry sez 200 {"id":"926ec3b22e28d306a90e63ed8935dedd"}
wow. sentry sez 200 {"id":"b128e31695adfef5b74aeab11dc83a54"}

...and ACCEPTED twice on the mock server. Every one of those four lines is printed by examples/example.djs itself — two directly, two from the callback it hands to the SDK. Drop the callback and the example goes completely silent while the mock still shows both ACCEPTEDs; that is the SDK's actual default.


How it actually reaches Sentry

Plainly: Dogescript compiles to JavaScript and inherits Node's networking. so https becomes require('https') and nothing more. Node opens the socket, Node speaks TLS, Node validates the certificate. Dogescript's contribution is deciding what bytes go into the envelope and which module gets handed them.

So yes, this SDK will talk to production Sentry over HTTPS — but it is Node doing the TLS, not a shibe. src/sentry.djs requires both http and https, reads the scheme off the DSN, and picks the matching module. The example points at a local mock over plain HTTP, which is also how you would point a real deployment at a local Sentry Relay that terminates TLS upstream.

The maybe situation

Dogescript ships a keyword called maybe. It compiles to !!+Math.round(Math.random()).

It appears nowhere in this SDK, deliberately. An error reporting client that flips a coin over whether to report your error is funny exactly once and infuriating every time after that. maybe is the language's only source of nondeterminism, so leaving it out makes every decision in this SDK — DSN parsing, transport selection, frame ordering, envelope framing — fully deterministic.

The one thing that legitimately varies per event is the event id, and that comes from crypto.randomBytes(16) rendered as 32 lowercase hex characters, the same way real Sentry SDKs do it.

try, catch, and the absence thereof

Dogescript has no try, no catch, and no throw. Not "awkward" — absent. There is no token for it.

That limits the SDK in exactly one place, and it is worth being precise about which: Dogescript cannot catch an error, but it can absolutely read one. It compiles to JavaScript, so a real Error handed to captureException behaves like a real Error — err giv name, err giv message and err giv stack all work. So captureException takes the genuine article rather than a (type, value) string pair, and getting an error into your hands is the part that needs the process-level lookout shown above.

examples/example.djs feeds JSON.parse something that is not JSON and lets the shibe bork in peace. A genuine V8 SyntaxError — thrown by real code, never constructed for show — arrives at the handler with a real stack.

Stack traces

sniffFrames walks err.stack with nothing but split, slice, indexOf and lastIndexOf (no regex literals — Dogescript's parser and / do not get along), pulling filename, function and lineno off each at ... line. Lines it cannot parse are dropped rather than guessed at; frames are never fabricated. An error whose stack yields no parseable frames is sent without a stacktrace at all.

V8 prints the crashing frame first. Sentry wants it last. So the parser reverses the list before sending, and the mock server echoes the received order back so you can check the direction:

  stacktrace, 10 frames, crashing frame last:
    node:internal/modules/run_main:154 in Module.executeUserEntryPoint [as runMain]
    ...
    shibe-app.js:34 in Object.<anonymous>
    shibe-app.js:30 in checkTheBowl
    shibe-app.js:25 in countTreats

countTreats is where it blew up, and it is last. Those line numbers point at the compiled .js, not the .djs. Dogescript emits no source maps, so the frames are honest about the file the runtime actually executed.

Timestamps

Date.now() is reachable, so every event carries a timestamp in Unix seconds.


The wire format, in full

Everything this SDK has to get right, inlined so you do not have to go looking.

DSN

<scheme>://<public_key>@<host>:<port>/<project_id>

init splits it on ://, @, : and the last /. No URL library involved. Production DSNs use https and omit the port. The SDK does not know or care whether the other end is Sentry or a local Relay.

Event JSON

A message event:

{"event_id":"0123456789abcdef0123456789abcdef","platform":"other","level":"info","timestamp":1787060117,"logentry":{"formatted":"HAI WORLD"}}

An exception event:

{"event_id":"0123456789abcdef0123456789abcdef","platform":"other","level":"error","timestamp":1787060117,"exception":{"values":[{"type":"TypeError","value":"Cannot read properties of null (reading 'reduce')","stacktrace":{"frames":[
  {"filename":"shibe-app.js","function":"Object.<anonymous>","lineno":34},
  {"filename":"shibe-app.js","function":"checkTheBowl","lineno":30},
  {"filename":"shibe-app.js","function":"countTreats","lineno":25}
]}}]}}

event_id is 32 lowercase hex characters, no dashes. timestamp is Unix seconds. Frames run oldest-first, so the crashing frame is last.

Envelope

Newline-separated JSON. Three lines, one trailing newline. The event id appears in both line 1 and line 3.

{"event_id":"<id>"}
{"type":"event"}
{"event_id":"<id>","platform":"other","level":"info",...}

The request

POST /api/<project_id>/envelope/ HTTP/1.1
Host: <host>:<port>
Content-Type: application/x-sentry-envelope
Content-Length: <byte length of body>
X-Sentry-Auth: Sentry sentry_version=7, sentry_key=<public_key>, sentry_client=sentry.dogescript/0.1.0
Connection: close

<the three lines above>

Content-Length is bytes, not characters — Buffer.byteLength(envelope, 'utf8') — or the server hangs waiting for a body that never finishes arriving.

A successful send returns 200 with {"id":"<event_id>"}.


Notes for the next shibe

Things learned the hard way about the Dogescript 2.4.3 compiler, in case they save you an afternoon:

  • A zero-argument much crashes the compiler, and not with a nice error — it dumps its own minified bundle to stderr. res dose on with 'end' much is fatal; res dose on with 'end' much fin is fine. Name the parameter you do not want.
  • plz foo with 'a' + b does not concatenate. The + is read as an argument separator and you get foo('a', +, b), which is not valid JavaScript. Build the string into a variable first, then pass the variable.
  • Calls do not nest as arguments. plz console.loge with plz makeId compiles to console.log(plz, makeId). Intermediate variables everywhere.
  • much i as 0 next ... does not declare i. It emits for (i = 0; ...), which throws under trained ("use strict"). Add a bare very i first.
  • Quoted require paths get mangled. so './sentry' as sentry becomes require(''. / sentry ''). Write the path bare: so ./sentry as sentry. Hyphenated package names are fine bare too: so sentry-dogescript as sentry.
  • console.loge is console.log, and there is no doge keyword for stderr. Write plz console.error with x — it passes through fine. The SDK uses only console.error, never console.loge, so it cannot touch your stdout.
  • Single quotes only. Four spaces, never tabs.

wow.

About

Prototype hackweek Sentry SDK for Dogescript — not an official Sentry SDK

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages