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.
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'
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
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.
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
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.
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.
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.
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), wherebodyis Sentry's{"id":"<event_id>"} - transport failure —
done(err) initnever called —done(err)and nothing is sent
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}.
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.
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.
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.
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.
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.
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.
Date.now() is reachable, so every event carries a timestamp in Unix seconds.
Everything this SDK has to get right, inlined so you do not have to go looking.
<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.
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.
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",...}
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>"}.
Things learned the hard way about the Dogescript 2.4.3 compiler, in case they save you an afternoon:
- A zero-argument
muchcrashes the compiler, and not with a nice error — it dumps its own minified bundle to stderr.res dose on with 'end' muchis fatal;res dose on with 'end' much finis fine. Name the parameter you do not want. plz foo with 'a' + bdoes not concatenate. The+is read as an argument separator and you getfoo('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 makeIdcompiles toconsole.log(plz, makeId). Intermediate variables everywhere. much i as 0 next ...does not declarei. It emitsfor (i = 0; ...), which throws undertrained("use strict"). Add a barevery ifirst.- Quoted require paths get mangled.
so './sentry' as sentrybecomesrequire(''. / sentry ''). Write the path bare:so ./sentry as sentry. Hyphenated package names are fine bare too:so sentry-dogescript as sentry. console.logeisconsole.log, and there is no doge keyword for stderr. Writeplz console.error with x— it passes through fine. The SDK uses onlyconsole.error, neverconsole.loge, so it cannot touch your stdout.- Single quotes only. Four spaces, never tabs.
wow.
