Log

Moduł Log służy do rejestrowania zdarzeń z wnętrza modułu. Logi są zbierane przez platformę Orbito i dostępne w panelu administracyjnym, co ułatwia diagnozowanie problemów na produkcji bez potrzeby logowania się na serwer.

Wszystkie metody przyjmują te same argumenty:

Log.info(message, data?)
Log.warn(message, data?)
Log.error(message, data?)

Parametr	Typ	Wymagany	Opis
`message`	`string`	Tak	Krótki opis zdarzenia
`data`	`object`	Nie	Dowolne dane kontekstowe w formacie JSON

Przypisanie logu do firmy

Nie przekazujesz companyId – platforma przypisuje log do firmy na podstawie tożsamości połączenia kontenera. Szczegóły w Kontekst firmy.

Log.info

Używaj do logowania normalnego przebiegu operacji – uruchomienia modułu, wywołań metod, zakończonych akcji.

const { Log } = require('@orbito/api-lib');

Log.info('Moduł uruchomiony');

// Z danymi kontekstowymi
Log.info('Zamówienie przetworzone', {
  orderId: order._id,
  total: order.total
});

// Na początku metody – do debugowania
Core.registerMethod('sync', async (params, ctx) => {
  Log.info('Rozpoczęto synchronizację', { params });

  // ... logika ...

  Log.info('Synchronizacja zakończona', { count: results.length });
  return { synced: results.length };
});

Log.warn

Używaj gdy operacja się powiodła, ale wystąpiła sytuacja potencjalnie problematyczna – np. brakujące dane opcjonalne, przestarzała konfiguracja, wysoki czas odpowiedzi zewnętrznego API.

Log.warn('Brak konfiguracji przewoźnika, używam wartości domyślnych');

Log.warn('Odpowiedź zewnętrznego API zajęła ponad 2s', {
  url: 'https://api.example.com/sync',
  durationMs: elapsed
});

Log.error

Używaj gdy operacja się nie powiodła w sposób wymagający uwagi – nieobsłużony wyjątek, błędna odpowiedź z zewnętrznego API, nieprawidłowe dane wejściowe.

Core.registerMethod('importOrders', async (params, ctx) => {
  try {
    const res = await Core.fetch('https://api.example.com/orders');

    if (!res.ok) {
      Log.error('Błąd pobierania zamówień z API', {
        status: res.status,
        url: 'https://api.example.com/orders'
      });
      return { success: false };
    }

    // ...
  } catch (err) {
    Log.error('Nieoczekiwany błąd importu', {
      error: err.message,
      stack: err.stack
    });
    throw err;
  }
});

Dobre praktyki

Nie loguj wrażliwych danych – haseł, tokenów API, danych osobowych. Logi są widoczne dla administratorów firmy.

// ❌ Nigdy
Log.info('Autoryzacja', { apiKey: config.apiKey, password: user.password });

// ✅ Zamiast tego
Log.info('Autoryzacja zakończona pomyślnie', { userId: user._id });

Loguj wejście i wyjście metod – ułatwia diagnozowanie problemów bez potrzeby dodawania debuggera:

Core.registerMethod('process', async (params, ctx) => {
  Log.info('process: start', { params });
  const result = await doWork(params);
  Log.info('process: done', { resultCount: result.items.length });
  return result;
});