+2 -1

docs/DEPLOYMENT.md

reviewed

··· 81 81 - `hostname`: the host relays should crawl 82 82 - `service_handle_domain`: the suffix used for local handles 83 83 - `jwt_secret`: required; the server now refuses to start if it is missing or still set to the old `perlsky-dev-secret` fallback 84 84 - - `sentry_dsn`: optional; when set, perlsky reports unhandled XRPC exceptions to Sentry 84 84 + - `sentry_dsn`: optional; when set, perlsky reports unhandled XRPC exceptions to Sentry with request context and Perl stack frames 85 85 - If you want users like `alice.pds.example.com`, set `service_handle_domain` to `pds.example.com`, not `example.com`. 86 86 - Public handle resolution for `alice.pds.example.com` also requires wildcard DNS for `*.pds.example.com` and a reverse proxy/TLS setup that will answer those subdomains. 87 87 - `invite_code_required`: if true, `createAccount` requires a valid invite code ··· 337 337 The current integration is intentionally narrow: 338 338 339 339 - it reports unhandled XRPC exceptions 340 340 + - the Sentry event includes request metadata and Perl stack frames 340 341 - it does not report ordinary handled XRPC errors like `InvalidToken` 341 342 - it is a no-op when `sentry_dsn` is unset 342 343

+1 -1

docs/METRICS.md

reviewed

··· 107 107 108 108 ## Sentry 109 109 110 110 - Prometheus is still the main place to watch rates and latency. If you also configure `sentry_dsn`, perlsky will report unhandled XRPC exceptions to Sentry. That works well as a complement to: 110 110 + Prometheus is still the main place to watch rates and latency. If you also configure `sentry_dsn`, perlsky will report unhandled XRPC exceptions to Sentry with request metadata and Perl stack frames. That works well as a complement to: 111 111 112 112 - `perlsky_xrpc_errors_total` for handled request failures 113 113 - `perlsky_xrpc_unhandled_exceptions_total` for internal 500-class failures

+82

lib/ATProto/PDS/Sentry.pm

reviewed

··· 34 34 return 0 unless $self->enabled; 35 35 36 36 my $message = $args{message} // 'Unhandled exception'; 37 37 + my $frames = _stacktrace_frames($message); 37 38 my $event = { 38 39 event_id => substr(sha1_hex(join q{|}, time, $$, rand(), $message), 0, 32), 39 40 timestamp => strftime('%Y-%m-%dT%H:%M:%SZ', gmtime), ··· 55 56 { 56 57 type => $args{type} // 'UnhandledXRPCException', 57 58 value => $message, 59 59 + (@$frames ? (stacktrace => { frames => $frames }) : ()), 58 60 }, 59 61 ], 60 62 }, ··· 88 90 return 0 unless $tx; 89 91 my $code = eval { $tx->result->code } // 0; 90 92 return ($code >= 200 && $code < 300) ? 1 : 0; 93 93 + } 94 94 + 95 95 + sub _stacktrace_frames ($message) { 96 96 + my @frames = _message_stack_frames($message)->@*; 97 97 + my %seen = map { _frame_key($_) => 1 } @frames; 98 98 + 99 99 + for my $frame (_caller_stack_frames()->@*) { 100 100 + my $key = _frame_key($frame); 101 101 + next if $seen{$key}++; 102 102 + push @frames, $frame; 103 103 + } 104 104 + 105 105 + return \@frames; 106 106 + } 107 107 + 108 108 + sub _message_stack_frames ($message) { 109 109 + return [] unless defined $message && length $message; 110 110 + 111 111 + my @frames; 112 112 + my @lines = split /\n/, $message; 113 113 + if (@lines && $lines[0] =~ / at (.+) line (\d+)\.?$/) { 114 114 + push @frames, { 115 115 + filename => $1, 116 116 + function => '<exception>', 117 117 + module => undef, 118 118 + lineno => 0 + $2, 119 119 + in_app => _in_app_filename($1), 120 120 + }; 121 121 + } 122 122 + 123 123 + for my $line (@lines[1 .. $#lines]) { 124 124 + next unless $line =~ /^\s*(.+?) called at (.+) line (\d+)\.?$/; 125 125 + push @frames, { 126 126 + filename => $2, 127 127 + function => $1, 128 128 + module => _module_from_function($1), 129 129 + lineno => 0 + $3, 130 130 + in_app => _in_app_filename($2), 131 131 + }; 132 132 + } 133 133 + 134 134 + return \@frames; 135 135 + } 136 136 + 137 137 + sub _caller_stack_frames () { 138 138 + my @frames; 139 139 + my $level = 1; 140 140 + while (my @caller = caller($level++)) { 141 141 + my ($package, $filename, $line, $subroutine) = @caller[0 .. 3]; 142 142 + next if defined $subroutine && $subroutine =~ /\AATProto::PDS::Sentry::(?:capture_exception|_stacktrace_frames|_message_stack_frames|_caller_stack_frames|_frame_key|_module_from_function|_in_app_filename)\z/; 143 143 + push @frames, { 144 144 + filename => $filename, 145 145 + function => $subroutine // '<main>', 146 146 + module => $package, 147 147 + lineno => 0 + $line, 148 148 + in_app => _in_app_filename($filename), 149 149 + }; 150 150 + } 151 151 + return [ reverse @frames ]; 152 152 + } 153 153 + 154 154 + sub _frame_key ($frame) { 155 155 + return join "\x1F", 156 156 + map { defined $_ ? $_ : q() } 157 157 + @{$frame}{qw(filename function lineno)}; 158 158 + } 159 159 + 160 160 + sub _module_from_function ($function) { 161 161 + return undef unless defined $function && length $function; 162 162 + return $1 if $function =~ /\A(.+)::[^:]+\z/; 163 163 + return undef; 164 164 + } 165 165 + 166 166 + sub _in_app_filename ($filename) { 167 167 + return 0 unless defined $filename && length $filename; 168 168 + return 0 if $filename =~ /^\(eval/; 169 169 + return 0 if $filename =~ m{(?:^|/)(?:core_perl|site_perl|vendor_perl)(?:/|$)}; 170 170 + return 0 if $filename =~ m{(?:^|/)local/lib/perl5(?:/|$)}; 171 171 + return 0 if $filename =~ m{^/usr/}; 172 172 + return 1; 91 173 } 92 174 93 175 sub _ua ($self) {

+34 -5

t/sentry.t

reviewed

··· 72 72 ); 73 73 $sentry->{ua} = SentryTestUA->new(\@requests); 74 74 75 75 - ok($sentry->enabled, 'sentry client is enabled when a DSN is configured'); 76 76 - ok( 77 77 - $sentry->capture_exception( 78 78 - message => 'intentional sentry test failure', 75 75 + sub sentry_nested_failure { 76 76 + die "intentional sentry test failure"; 77 77 + } 78 78 + 79 79 + sub sentry_emit_nested_failure { 80 80 + eval { sentry_nested_failure(); 1 }; 81 81 + my $err = $@; 82 82 + return $sentry->capture_exception( 83 83 + message => $err, 79 84 method => 'GET', 80 85 nsid => 'com.atproto.server.describeServer', 81 86 endpoint_type => 'query', 82 87 status => 500, 83 88 did => 'did:plc:test', 84 84 - ), 89 89 + ); 90 90 + } 91 91 + 92 92 + ok($sentry->enabled, 'sentry client is enabled when a DSN is configured'); 93 93 + ok( 94 94 + sentry_emit_nested_failure(), 85 95 'capture_exception reports success for a 200 response', 86 96 ); 87 97 is(scalar @requests, 1, 'capture_exception submits one store request'); ··· 91 101 is($requests[0]{payload}{exception}{values}[0]{type}, 'UnhandledXRPCException', 'payload includes exception type'); 92 102 like($requests[0]{payload}{exception}{values}[0]{value}, qr/intentional sentry test failure/, 'payload includes exception message'); 93 103 is($requests[0]{payload}{user}{id}, 'did:plc:test', 'payload includes the actor did when available'); 104 104 + ok( 105 105 + ref($requests[0]{payload}{exception}{values}[0]{stacktrace}{frames}) eq 'ARRAY' 106 106 + && @{$requests[0]{payload}{exception}{values}[0]{stacktrace}{frames}}, 107 107 + 'payload includes stacktrace frames', 108 108 + ); 109 109 + ok( 110 110 + scalar(grep { 111 111 + ($_->{filename} // q()) =~ m{(?:^|/)t/sentry\.t$} 112 112 + && ($_->{function} // q()) =~ /sentry_nested_failure|<exception>/ 113 113 + } @{$requests[0]{payload}{exception}{values}[0]{stacktrace}{frames}}), 114 114 + 'payload stacktrace points at the test failure site', 115 115 + ); 116 116 + ok( 117 117 + scalar(grep { 118 118 + ($_->{filename} // q()) =~ m{(?:^|/)t/sentry\.t$} 119 119 + && ($_->{function} // q()) =~ /sentry_emit_nested_failure/ 120 120 + } @{$requests[0]{payload}{exception}{values}[0]{stacktrace}{frames}}), 121 121 + 'payload stacktrace includes the caller frame', 122 122 + ); 94 123 95 124 my $root = File::Spec->rel2abs(File::Spec->catdir($Bin, '..')); 96 125 my $tmp = tempdir(CLEANUP => 1);